libdragon 11.0.0 → 11.0.2

package/README.md

@@ -54,7 +54,7 @@ Download the [pre-built executable](https://github.com/anacierdem/libdragon-dock
 Install [node.js](https://nodejs.org/en/download/) (`>= 18`) and install `libdragon` as a global NPM package;
 
 ```bash
-    npm install -g libdragon
+npm install -g libdragon
 ```
 
 To update the tool to the latest, do `npm i -g libdragon@latest`.
@@ -64,23 +64,23 @@ To update the tool to the latest, do `npm i -g libdragon@latest`.
 Navigate to the folder you want to initialize your project and invoke libdragon;
 
 ```bash
-    libdragon init
+libdragon init
 ```
 
-On first `init` an example project will be created, the container will be downloaded, started and latest libdragon will get installed on it with all the example ROMs built. You can find all the example ROMs in the `libdragon` folder.
+On first `init` an example project will be created, the container will be downloaded, started and latest libdragon will get installed on it with all the example ROMs built. You can find all the example ROMs in the `libdragon/examples` folder.
 
 The container's `make` can be invoked on your current working directory via;
 
-```
-    libdragon make
+```bash
+libdragon make
 ```
 
 Any additonal parameters are passed down to the actual make command. You can work on the files simultaneously with the docker container and any built artifacts will be available in project directory as it is mounted on the container.
 
 To update the library and rebuild/install all the artifacts;
 
-```
-    libdragon update
+```bash
+libdragon update
 ```
 
 In general, you can invoke libdragon as follows;
@@ -96,20 +96,20 @@ Run `libdragon help [action]` for more details on individual actions.
 Initialize your project as usual:
 
 ```bash
-    libdragon init
+libdragon init
 ```
 
 Then switch the submodule to the desired branch:
 
 ```bash
-    git -C ./libdragon checkout opengl
-    libdragon install
+git -C ./libdragon checkout opengl
+libdragon install
 ```
 
 If your changes are on a different remote, then you will need to manage your git remotes as usual. If you also want to update the remote tracking branch for the submodule, run:
 
 ```bash
-    git submodule set-branch -b opengl libdragon
+git submodule set-branch -b opengl libdragon
 ```
 
 This will update the branch on `.gitmodules` and if you commit that change, subsequent initializations will use the `opengl` branch by default.
@@ -119,19 +119,16 @@ This will update the branch on `.gitmodules` and if you commit that change, subs
 As libdragon is an actively developed library, you may find yourself at a position where you want to change a few things on it and see how it works. In general, if you modify the files in `libdragon` folder of your project, you can install that version to the docker container by simply running:
 
 ```bash
-    libdragon install
+libdragon install
 ```
 
 This will update all the artifacts in your container and your new code will start linking against the new version when you re-build it via `libdragon make`. The build system should pick up the change in the library and re-compile the dependent files.
 
-Instead of depending on the above command, you can re-build the library by making it a make dependency in your project:
+Instead of depending on the above command, you can automatically re-build the library by making it a make dependency in your project:
 
 ```makefile
-libdragon-install: libdragon
+libdragon-install:
 	$(MAKE) -C ./libdragon install
-
-libdragon:
-	$(MAKE) -C ./libdragon
 ```
 
 If your build now depends on `libdragon-install`, it will force an install (which should be pretty quick if you don't have changes) and force the build system to rebuild your project when necessary.
@@ -153,19 +150,19 @@ To be able to share your project with the library change, you just commit your c
 After cloning this repository on a system with node.js (`>= 18`) & docker (`>= 24`), in this repository's root do;
 
 ```bash
-    npm install
+npm install
 ```
 
 This will install all necessary NPM dependencies. Now it is time to get the original libdragon repository. (you can also clone this repository with `--recurse-submodules`)
 
 ```bash
-    git submodule update --init
+git submodule update --init
 ```
 
 Then run;
 
 ```bash
-    npm run libdragon -- init
+npm run libdragon -- init
 ```
 
 to download the pre-built toolchain image, start and initialize it. This will also install [test bench](#local-test-bench) dependencies into the container if any.
@@ -175,23 +172,22 @@ Now you will be able to work on the files simultaneously with the docker contain
 There is a root `Makefile` making deeper makefiles easier with these recipes;
 
     bench: build the test bench (see below)
-    examples: re-build libdragon examples
-    tests: re-build the test ROM
-    libdragon: build libdragon itself
-    libdragon-install: install libdragon
+    examples: build libdragon examples
+    tests: build the test ROM
+    libdragon-install: build and install libdragon
     clean-bench: clean the test bench (see below)
     clean: clean everything and start from scratch
 
 For example, to re-build the original libdragon examples do;
 
 ```bash
-    npm run libdragon -- make examples
+npm run libdragon -- make examples
 ```
 
 Similarly to run the `clean` recipe, run;
 
 ```bash
-    npm run libdragon -- make clean
+npm run libdragon -- make clean
 ```
 
 Keep in mind that `--` is necessary for actual arguments when using npm scripts.
@@ -199,21 +195,25 @@ Keep in mind that `--` is necessary for actual arguments when using npm scripts.
 To update the submodule and re-build everything;
 
 ```bash
-    npm run libdragon -- update
+npm run libdragon -- update
 ```
 
 ### Local test bench
 
-This repository also uses [ed64](https://github.com/anacierdem/ed64), so you can just hit F5 on vscode (The `Run Test Bench` launch configuration) to run the test code in `src` folder to develop libdragon itself quicker if you have an everdrive.
+The root `bench` recipe is for building the code in root `src` folder. This is a quick way of testing your libdragon changes or a sample code built around libdragon, and is called the test bench. This recipe together with `examples` and `tests` recipes will build and install libdragon automatically as necessary. Thus, they will always produce a rom image using the libdragon code in the repository via their make dependencies, which is ideal for experimenting with libdragon itself. 
+
+There are also vscode launch configurations to quickly build the examples, tests and the bench. If you have the `N64_EMU` environment variable set pointing at your favourite emulator ([ares](https://ares-emu.net/) is highly recommended), the launch configurations ending in `(emu)` will kick your emulator with the selected example/code. You can also just hit F5 to launch the selected configuration.
+
+This repository also uses [ed64](https://github.com/anacierdem/ed64), so you can use the launch configurations without `(emu)` to run the code if you have an everdrive plugged in and your active configuration will just boot up.
 
-There are also additional vscode launch configurations to build libdragon examples and tests based on the currently built and installed libdragon in the docker container. Most of these will always rebuild so that they will use the latest if you made and installed an alternative libdragon. The test bench itself and a few examples (that use the new build system) will already rebuild and reinstall libdragon automatically. These will always produce a rom image using the latest libdragon code in the active repository via its make dependencies. You can clean everything with the `clean` task (open the command palette and choose `Run Task -> clean`).
+You can clean everything with the `clean` recipe/task (open the command palette and choose `Run Task -> clean`).
 
 ### Developing the tool itself
 
 For a quick development loop it really helps linking the code in this repository as the global libdragon installation. To do this run;
 
 ```bash
-    npm link
+npm link
 ```
 
 in the root of the repository. Once you do this, running `libdragon` will use the code here rather than the actual npm installation. Then you can test your changes in the libdragon project here or elsewhere on your computer. This setup is automatically done if you use the [devcontainer](#experimental-devcontainer-support).
@@ -221,26 +221,26 @@ in the root of the repository. Once you do this, running `libdragon` will use th
 When you are happy with your changes, you can verify you conform to the coding standards via:
 
 ```bash
-    npm run format-check
-    npm run lint-check
+npm run format-check
+npm run lint-check
 ```
 
 You can auto-fix applicable errors by running `format` and `lint` scripts instead. Additionally, typescript is used as the type system. To be able to get away with transpiling the code during development, jsDoc flavor of types are used instead of inline ones. To check your types, run:
 
 ```bash
-    npm run tsc
+npm run tsc
 ```
 
 To run the test suite:
 
 ```bash
-    npm run test
+npm run test
 ```
 
 This repository uses [`semantic-release`](https://github.com/semantic-release/semantic-release) and manages releases from specially formatted commit messages. To simplify creating them you can use:
 
 ```bash
-    npx cz
+npx cz
 ```
 
 It will create a `semantic-release` compatible commit from your current staged changes.

package/modules/actions/init.js

@@ -9,6 +9,7 @@ const {
   initGitAndCacheContainerId,
   updateImage,
   runGitMaybeHost,
+  destroyContainer,
 } = require('./utils');
 
 const {
@@ -26,7 +27,6 @@ const {
   toPosixPath,
   toNativePath,
 } = require('../helpers');
-const { syncImageAndStart } = require('./update-and-start');
 
 /**
  * @param {import('../project-info').LibdragonInfo} info
@@ -226,13 +226,22 @@ async function init(info) {
     );
     if (!process.env.DOCKER_CONTAINER) {
       if (info.options.DOCKER_IMAGE) {
-        info = await syncImageAndStart(info);
-      } else {
+        // The logic here resembles syncImageAndStart but it aims at being idempotent
+        // w.r.t the container when called without any additional flag.
+        // Download the new image and if it is different, re-create the container
+        if (await updateImage(info, info.options.DOCKER_IMAGE)) {
+          await destroyContainer(info);
+        }
+
         info = {
           ...info,
-          containerId: await start(info),
+          imageName: info.options.DOCKER_IMAGE,
         };
       }
+      info = {
+        ...info,
+        containerId: await start(info),
+      };
     }
 
     info = await autoVendor(info);
@@ -241,6 +250,12 @@ async function init(info) {
   }
 
   if (!process.env.DOCKER_CONTAINER) {
+    // We don't have a config yet, this is a fresh project, override with the
+    // image flag if provided. Also see https://github.com/anacierdem/libdragon-docker/issues/66
+    info = {
+      ...info,
+      imageName: info.options.DOCKER_IMAGE ?? info.imageName,
+    };
     // Download image and start it
     await updateImage(info, info.imageName);
     info.containerId = await start(info);
@@ -274,7 +289,7 @@ module.exports = /** @type {const} */ ({
   usage: {
     name: 'init',
     summary: 'Create a libdragon project in the current directory.',
-    description: `Creates a libdragon project in the current directory. Every libdragon project will have its own docker container instance. If you are in a git repository or an NPM project, libdragon will be initialized at their root also marking there with a \`.libdragon\` folder. Do not remove the \`.libdragon\` folder and commit its contents if you are using source control, as it keeps persistent libdragon project information.
+    description: `Creates a libdragon project in the current directory. Every libdragon project will have its own docker container instance. If you are in a git repository or an NPM project, libdragon will be initialized at their root also marking there with a \`.libdragon\` folder. When running in a submodule, initializion will take place at that level rather than the superproject. Do not remove the \`.libdragon\` folder and commit its contents if you are using source control, as it keeps persistent libdragon project information.
 
     By default, a git repository and a submodule at \`./libdragon\` will be created to automatically update the vendored libdragon files on subsequent \`update\`s. If you intend to opt-out from this feature, see the \`--strategy manual\` flag to provide your self-managed libdragon copy. The default behaviour is intended for users who primarily want to consume libdragon as is.
 

package/modules/actions/update.js

@@ -1,7 +1,48 @@
-const { log } = require('../helpers');
+const { log, assert } = require('../helpers');
 const { LIBDRAGON_GIT, LIBDRAGON_BRANCH } = require('../constants');
-const { runGitMaybeHost, installDependencies } = require('./utils');
-const { syncImageAndStart } = require('./update-and-start');
+const {
+  runGitMaybeHost,
+  installDependencies,
+  updateImage,
+  destroyContainer,
+} = require('./utils');
+const { start } = require('./start');
+
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
+async function syncImageAndStart(libdragonInfo) {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error(
+      '[syncImageAndStart] We should already know we are in a container.'
+    )
+  );
+
+  const oldImageName = libdragonInfo.imageName;
+  const imageName = libdragonInfo.options.DOCKER_IMAGE ?? oldImageName;
+  // If an image is provided, always attempt to install it
+  // See https://github.com/anacierdem/libdragon-docker/issues/47
+  if (oldImageName !== imageName) {
+    log(`Updating image from \`${oldImageName}\` to \`${imageName}\``);
+  } else {
+    log(`Updating image \`${oldImageName}\``);
+  }
+
+  // Download the new image and if it is different, re-create the container
+  if (await updateImage(libdragonInfo, imageName)) {
+    await destroyContainer(libdragonInfo);
+  }
+
+  return {
+    ...libdragonInfo,
+    imageName,
+    containerId: await start({
+      ...libdragonInfo,
+      imageName,
+    }),
+  };
+}
 
 /**
  * @param {import('../project-info').LibdragonInfo} info

package/modules/actions/utils.js

@@ -242,7 +242,19 @@ async function initGitAndCacheContainerId(libdragonInfo) {
     await runGitMaybeHost(libdragonInfo, ['init']);
   }
 
-  const gitFolder = path.join(libdragonInfo.root, '.git');
+  const rootGitFolder = (
+    await spawnProcess('git', [
+      'rev-parse',
+      '--show-superproject-working-tree',
+    ]).catch(() => {
+      // Probably host does not have git, can ignore
+      return '';
+    })
+  ).trim();
+
+  // Fallback to the potential git root on the project root if there is no parent
+  // git project.
+  const gitFolder = path.join(rootGitFolder || libdragonInfo.root, '.git');
   if (await dirExists(gitFolder)) {
     await fs.writeFile(
       path.join(gitFolder, CACHED_CONTAINER_FILE),

package/modules/project-info.js

@@ -75,6 +75,8 @@ async function findContainerId(libdragonInfo) {
     return id;
   }
 
+  // TODO: use docker container ls -a --format "{{.Labels}}" instead
+  // from what I remember this used to not work (i.e the property was not exposed before)
   const candidates = (
     await spawnProcess('docker', [
       'container',
@@ -186,9 +188,6 @@ const readProjectInfo = async function (optionInfo) {
     // Only used for the init action ATM, and it is not ideal to have this here
     haveProjectConfig: !!projectRoot,
 
-    // Set the defaults immediately, these should be present at all times even
-    // if we are migrating from the old config because they did not exist before
-    imageName: DOCKER_HUB_IMAGE,
     vendorDirectory: toPosixPath(path.join('.', LIBDRAGON_SUBMODULE)),
     vendorStrategy: DEFAULT_STRATEGY,
   };
@@ -212,10 +211,6 @@ const readProjectInfo = async function (optionInfo) {
     log(`Active container id: ${info.containerId}`, true);
   }
 
-  // For imageName, flag has the highest priority followed by the one read from
-  // the file and then if there is any matching container, name is read from it.
-  // As last option fallback to default value.
-
   // If still have the container, read the image name from it
   // No need to do anything if we are in a container
   if (
@@ -235,6 +230,14 @@ const readProjectInfo = async function (optionInfo) {
     ).trim();
   }
 
+  // For imageName, flag has the highest priority followed by the one read from
+  // the file and then if there is any matching container, name is read from it.
+  // As last option fallback to default value.
+  // This represents the current value, so the flag should be processed later.
+  // If we were to update it here, it would be impossible to know the change
+  // with how we structure the code right now.
+  info.imageName = info.imageName ?? DOCKER_HUB_IMAGE;
+
   log(`Active image name: ${info.imageName}`, true);
   log(`Active vendor directory: ${info.vendorDirectory}`, true);
   log(`Active vendor strategy: ${info.vendorStrategy}`, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libdragon",
-  "version": "11.0.0",
+  "version": "11.0.2",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {
@@ -12,6 +12,7 @@
   },
   "scripts": {
     "test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --watch",
     "libdragon": "node index.js",
     "start": "node index.js start",
     "stop": "node index.js stop",

package/modules/actions/update-and-start.js

@@ -1,43 +0,0 @@
-const { log, assert } = require('../helpers');
-const { updateImage, destroyContainer } = require('./utils');
-const { start } = require('./start');
-
-/**
- * @param {import('../project-info').LibdragonInfo} libdragonInfo
- */
-async function syncImageAndStart(libdragonInfo) {
-  assert(
-    !process.env.DOCKER_CONTAINER,
-    new Error(
-      '[syncImageAndStart] We should already know we are in a container.'
-    )
-  );
-
-  const oldImageName = libdragonInfo.imageName;
-  const imageName = libdragonInfo.options.DOCKER_IMAGE ?? oldImageName;
-  // If an image is provided, always attempt to install it
-  // See https://github.com/anacierdem/libdragon-docker/issues/47
-  if (oldImageName !== imageName) {
-    log(`Updating image from \`${oldImageName}\` to \`${imageName}\``);
-  } else {
-    log(`Updating image \`${oldImageName}\``);
-  }
-
-  // Download the new image and if it is different, re-create the container
-  if (await updateImage(libdragonInfo, imageName)) {
-    await destroyContainer(libdragonInfo);
-  }
-
-  return {
-    ...libdragonInfo,
-    imageName,
-    containerId: await start({
-      ...libdragonInfo,
-      imageName,
-    }),
-  };
-}
-
-module.exports = {
-  syncImageAndStart,
-};