libdragon 11.1.2 → 11.2.0

package/README.md

@@ -6,30 +6,34 @@ This is a wrapper for a docker container to make managing the libdragon toolchai
 
 ## Prerequisites
 
-You should have [docker](https://www.docker.com/products/docker-desktop) (`>= 24`) installed on your system.
+You should have [docker](https://www.docker.com/products/docker-desktop) (`>= 27.2.0`) installed on your system.
 
 `git` is not strictly required to use the tool. Still, it is highly recommended to have git on your host machine as it will be used instead of the one in the container.
 
 ## Installation
 
-This is primarily a node.js script which is also packaged as an executable. You have two options:
+This is primarily a node.js script which is also packaged as an executable. You have a few options:
 
-### pre-built
+### installer
 
-Download the [pre-built executable](https://github.com/anacierdem/libdragon-docker/releases/latest) for your system and put it somewhere on your PATH. It is discouraged to put it in your project folder.
+Download the [windows installer](https://github.com/anacierdem/libdragon-docker/releases/latest) and run it. This option is currently only available on Windows.
 
 <details>
-  <summary>Windows instructions</summary>
+  <summary>Detailed instructions</summary>
 
   - Download the Windows installer and run it
-  - It can show a "Windows protected your PC" warning. In that case click "More info" and "Run anyway".
+  - It can show a "Windows protected your PC" warning. Click "More info" and "Run anyway".
   - You should now be able to use the `libdragon` on a command line or PowerShell.
   - To update it with a new version, download a newer installer and repeat the steps above.
 
 </details>
 
+### pre-built executable
+
+Download the [pre-built executable](https://github.com/anacierdem/libdragon-docker/releases/latest) for your system and put it somewhere on your PATH. It is discouraged to put it in your project folder.
+
 <details>
-  <summary>Windows instructions (manual)</summary>
+  <summary>Windows instructions</summary>
 
   - Download the Windows executable and copy it to `C:\bin`
   - Press `Windows + R` key combination and then enter `rundll32 sysdm.cpl,EditEnvironmentVariables`
@@ -101,15 +105,19 @@ Run `libdragon help [action]` for more details on individual actions.
 
 ## Recipes
 
-### Using a different branch of libdragon
+### Using a different libdragon branch
 
-Initialize your project as usual:
+Use the `--branch` flag to set up a custom libdragon branch when initializing your project:
 
 ```bash
-libdragon init
+libdragon init --branch unstable
 ```
 
-Then switch the submodule to the desired branch:
+This will use the `unstable` toolchain and code.
+
+### Switching to a different branch of libdragon
+
+On an already initialized project, switch the submodule to the desired branch:
 
 ```bash
 git -C ./libdragon checkout opengl
@@ -157,7 +165,7 @@ To be able to share your project with the library change, you just commit your c
 
 ## Working on this repository
 
-After cloning this repository on a system with node.js (`>= 18`) & docker (`>= 24`), in this repository's root do;
+After cloning this repository on a system with node.js (`>= 18`) & docker (`>= 27.2.0`), in this repository's root do;
 
 ```bash
 npm install
@@ -200,7 +208,9 @@ Similarly to run the `clean` recipe, run;
 npm run libdragon -- make clean
 ```
 
-Keep in mind that `--` is necessary for actual arguments when using npm scripts.
+> [!IMPORTANT]
+> Keep in mind that `--` is necessary for actual arguments when using npm scripts.
+
 
 To update the submodule and re-build everything;
 
@@ -214,7 +224,8 @@ The root `bench` recipe is for building the code in root `src` folder. This is a
 
 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.
+> [!NOTE]
+> 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.
 
 You can clean everything with the `clean` recipe/task (open the command palette and choose `Run Task -> clean`).
 
@@ -278,7 +289,12 @@ To create your own dev container backed project, you can use the contents of the
   - It will prepare the container and open it in the editor.
 </details>
 
-## As an NPM dependency
+## Dependency management
+
+> [!WARNING]
+> This is an experimental feature.
+
+### As an NPM dependency
 
 You can install libdragon as an NPM dependency by `npm install libdragon --save` in order to use docker in your N64 projects. A `libdragon` command similar to global intallation is provided that can be used in your NPM scripts as follows;
 
@@ -292,7 +308,7 @@ You can install libdragon as an NPM dependency by `npm install libdragon --save`
 
 See [here](https://github.com/anacierdem/ed64-example) for a full example.
 
-## Developing a dependency
+### Developing a dependency
 
 You can make an NPM package that a `libdragon` project can depend on. Just include a `Makefile` on the repository root with a default recipe and an `install` recipe. On the depending project, after installing libdragon and the dependency with `npm install <dep name> --save`, one can install libdragon dependencies on the current docker container using `package.json` scripts.
 
@@ -317,8 +333,6 @@ For example this `package.json` in the dependent project;
 
 will init the container for this project and run `make && make install` for `ed64` upon running `npm install`. To develop a dependency [this](https://github.com/anacierdem/libdragon-dependency) is a good starting point.
 
-This is an experimental dependency management.
-
 ## Funding
 
 If this tool helped you, consider supporting its development by sponsoring it!

package/modules/actions/init.js

@@ -16,7 +16,6 @@ const {
 const {
   LIBDRAGON_PROJECT_MANIFEST,
   LIBDRAGON_SUBMODULE,
-  LIBDRAGON_BRANCH,
   LIBDRAGON_GIT,
 } = require('../constants');
 const {
@@ -27,6 +26,7 @@ const {
   ValidationError,
   toPosixPath,
   toNativePath,
+  getImageName,
 } = require('../helpers');
 
 /**
@@ -45,11 +45,15 @@ const autoDetect = async (info) => {
 
   if (
     vendorTargetExists &&
-    (await runGitMaybeHost(info, [
-      'submodule',
-      'status',
-      info.vendorDirectory,
-    ]).catch((e) => {
+    (await runGitMaybeHost(
+      info,
+      ['submodule', 'status', info.vendorDirectory],
+      {
+        inheritStdin: false,
+        inheritStdout: false,
+        inheritStderr: false,
+      }
+    ).catch((e) => {
       if (!(e instanceof CommandError)) {
         throw e;
       }
@@ -148,7 +152,7 @@ const autoVendor = async (info) => {
         '--name',
         LIBDRAGON_SUBMODULE,
         '--branch',
-        LIBDRAGON_BRANCH,
+        info.activeBranchName,
         LIBDRAGON_GIT,
         info.vendorDirectory,
       ]);
@@ -156,6 +160,9 @@ const autoVendor = async (info) => {
       if (!(e instanceof CommandError)) throw e;
       // We speculate this is caused by the user, so replace it with a more useful error message.
       e.message = `Unable to create submodule. If you have copied the executable in your project folder or you have a file named ${info.vendorDirectory}, removing it might solve this issue. Original error:\n${e.message}`;
+      if (e.out) {
+        e.message += `\n${e.out}`;
+      }
       throw e;
     }
 
@@ -189,7 +196,7 @@ const autoVendor = async (info) => {
       '--prefix',
       path.relative(info.root, info.vendorDirectory),
       LIBDRAGON_GIT,
-      LIBDRAGON_BRANCH,
+      info.activeBranchName,
       '--squash',
     ]);
     return info;
@@ -252,11 +259,44 @@ 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
+    let activeBranchName = info.options.BRANCH ?? info.activeBranchName;
+    let shouldOverrideBranch = !!info.options.BRANCH;
+
+    if ((await autoDetect(info)) === 'submodule') {
+      try {
+        const existingBranchName = await runGitMaybeHost(
+          info,
+          [
+            '-C',
+            path.relative(info.root, info.vendorDirectory),
+            'rev-parse',
+            '--abbrev-ref',
+            'HEAD',
+          ],
+          {
+            inheritStdin: false,
+            inheritStdout: false,
+            inheritStderr: false,
+          }
+        );
+        activeBranchName = existingBranchName.trim();
+        shouldOverrideBranch = !!activeBranchName;
+      } catch {
+        // If we can't get the branch name, we will use the default
+      }
+    }
+
     info = {
       ...info,
-      imageName: info.options.DOCKER_IMAGE ?? info.imageName,
+      activeBranchName,
+      // 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
+      // Next, if `--branch` flag is provided use that or the one recovered from
+      // the submodule.
+      imageName:
+        (info.options.DOCKER_IMAGE ??
+          (shouldOverrideBranch && getImageName(activeBranchName))) ||
+        info.imageName,
     };
     // Download image and start it
     await updateImage(info, info.imageName);
@@ -299,6 +339,16 @@ module.exports = /** @type {const} */ ({
     If this is the first time you are creating a libdragon project at that location, this action will also create skeleton project files to kickstart things with the given image, if provided. For subsequent runs without any parameter, it will act like \`start\` thus can be used to revive an existing project without modifying it.
 
     If you have an existing project with an already vendored submodule or subtree libdragon copy, \`init\` will automatically detect it at the provided \`--directory\`.`,
-    group: ['docker', 'vendoring'],
+    group: ['docker', 'vendoring', '_none'],
+
+    optionList: [
+      {
+        name: 'branch',
+        description:
+          'Provide a different branch to initialize libdragon. It will also change the toolchain docker image to be based on the given branch but `--image` will have precedence. Defaults to `trunk` & `latest` image.',
+        alias: 'b',
+        typeLabel: '<branch>',
+      },
+    ],
   },
 });

package/modules/actions/update.js

@@ -1,5 +1,5 @@
 const { log, assert } = require('../helpers');
-const { LIBDRAGON_GIT, LIBDRAGON_BRANCH } = require('../constants');
+const { LIBDRAGON_GIT } = require('../constants');
 const {
   runGitMaybeHost,
   installDependencies,
@@ -69,7 +69,7 @@ const update = async (info) => {
       '--prefix',
       info.vendorDirectory,
       LIBDRAGON_GIT,
-      LIBDRAGON_BRANCH,
+      info.activeBranchName,
       '--squash',
     ]);
   }

package/modules/constants.js

@@ -1,5 +1,5 @@
 module.exports = /** @type {const} */ ({
-  DOCKER_HUB_IMAGE: 'ghcr.io/dragonminded/libdragon:latest',
+  DOCKER_HUB_IMAGE: 'ghcr.io/dragonminded/libdragon',
   LIBDRAGON_GIT: 'https://github.com/DragonMinded/libdragon',
   LIBDRAGON_BRANCH: 'trunk',
   LIBDRAGON_SUBMODULE: 'libdragon',

package/modules/helpers.js

@@ -5,7 +5,11 @@ const chalk = require('chalk').stderr;
 const { spawn } = require('child_process');
 
 const { globals } = require('./globals');
-const { NO_PROJECT_ACTIONS } = require('./constants');
+const {
+  NO_PROJECT_ACTIONS,
+  LIBDRAGON_BRANCH,
+  DOCKER_HUB_IMAGE,
+} = require('./constants');
 
 /**
  * A structure to keep additional error information
@@ -392,7 +396,7 @@ async function copyDirContents(src, dst) {
           await fs.writeFile(dest, content, {
             flag: 'wx',
           });
-        } catch (e) {
+        } catch {
           log(`${dest} already exists, skipping.`);
           return;
         }
@@ -454,8 +458,8 @@ function log(text, verboseOnly = false) {
 }
 
 /**
- * @param {import('./project-info').CLIInfo | import('./project-info').LibdragonInfo} info
- * @returns {info is import('./project-info').LibdragonInfo}
+ * @param {import('./project-info').CLIInfo} info
+ * @returns {info is import('./project-info').ProjectInfo}
  */
 function isProjectAction(info) {
   return !NO_PROJECT_ACTIONS.includes(
@@ -465,6 +469,18 @@ function isProjectAction(info) {
   );
 }
 
+/**
+ * @param {string} branchName
+ * @returns {string}
+ */
+function getImageName(branchName) {
+  return (
+    DOCKER_HUB_IMAGE +
+    ':' +
+    (branchName === LIBDRAGON_BRANCH ? 'latest' : branchName)
+  );
+}
+
 module.exports = {
   spawnProcess,
   toPosixPath,
@@ -480,4 +496,5 @@ module.exports = {
   ParameterError,
   ValidationError,
   isProjectAction,
+  getImageName,
 };

package/modules/npm-utils.js

@@ -121,7 +121,16 @@ const installNPMDependencies = async (libdragonInfo) => {
 function runNPM(params) {
   return spawnProcess(
     /^win/.test(process.platform) ? 'npm.cmd' : 'npm',
-    params
+    params,
+    {
+      userCommand: false,
+      inheritStdin: true,
+      inheritStdout: false,
+      inheritStderr: false,
+      spawnOptions: {
+        shell: true,
+      },
+    }
   );
 }
 module.exports = {

package/modules/parameters.js

@@ -19,6 +19,7 @@ const { globals } = require('./globals');
  *  VENDOR_DIR?: string;
  *  VENDOR_STRAT?: VendorStrategy;
  *  FILE?: string;
+ *  BRANCH?: string;
  * }} CommandlineOptions
  */
 
@@ -81,6 +82,14 @@ const parseParameters = async (argv) => {
       continue;
     }
 
+    if (['--branch', '-b'].includes(val)) {
+      options.BRANCH = argv[++i];
+      continue;
+    } else if (val.indexOf('--branch=') === 0) {
+      options.BRANCH = val.split('=')[1];
+      continue;
+    }
+
     if (val.indexOf('-') == 0) {
       log(chalk.red(`Invalid flag \`${val}\``));
       process.exit(STATUS_BAD_PARAM);
@@ -126,7 +135,7 @@ const parseParameters = async (argv) => {
     ) &&
     options.DOCKER_IMAGE
   ) {
-    log(chalk.red('Invalid flag: image'));
+    log(chalk.red('Invalid flag: --image'));
     process.exit(STATUS_BAD_PARAM);
   }
 
@@ -138,7 +147,19 @@ const parseParameters = async (argv) => {
     ) &&
     options.FILE
   ) {
-    log(chalk.red('Invalid flag: file'));
+    log(chalk.red('Invalid flag: --file'));
+    process.exit(STATUS_BAD_PARAM);
+  }
+
+  if (
+    !(
+      /** @type {typeof actions[keyof actions][]} */ ([actions.init]).includes(
+        options.CURRENT_ACTION
+      )
+    ) &&
+    options.BRANCH
+  ) {
+    log(chalk.red('Invalid flag: --branch'));
     process.exit(STATUS_BAD_PARAM);
   }
 

package/modules/project-info.js

@@ -12,11 +12,11 @@ const { findNPMRoot } = require('./npm-utils');
 const {
   LIBDRAGON_PROJECT_MANIFEST,
   CONFIG_FILE,
-  DOCKER_HUB_IMAGE,
   DEFAULT_STRATEGY,
   LIBDRAGON_SUBMODULE,
   CACHED_CONTAINER_FILE,
   CONTAINER_TARGET_PATH,
+  LIBDRAGON_BRANCH,
 } = require('./constants');
 
 const {
@@ -27,6 +27,7 @@ const {
   assert,
   ParameterError,
   isProjectAction,
+  getImageName,
 } = require('./helpers');
 
 /**
@@ -49,13 +50,18 @@ const {
  *
  * @typedef { {
  *  options: ActionsWithProjectOptions
+ * } } ProjectInfo
+ *
+ * @typedef { {
+ *  options: ActionsWithProjectOptions
  *  root: string;
  *  userInfo: os.UserInfo<string>;
  *  haveProjectConfig: boolean;
  *  imageName: string;
  *  vendorDirectory: string;
  *  vendorStrategy: import('./parameters').VendorStrategy;
- *  containerId?: string
+ *  containerId?: string;
+ *  activeBranchName: string;
  * } } LibdragonInfo
  */
 
@@ -189,6 +195,13 @@ const readProjectInfo = async function (optionInfo) {
 
     vendorDirectory: toPosixPath(path.join('.', LIBDRAGON_SUBMODULE)),
     vendorStrategy: DEFAULT_STRATEGY,
+
+    activeBranchName: LIBDRAGON_BRANCH,
+
+    // This is invalid at this point, but is overridden below from config file
+    // or container if it doesn't exist in the file. If a flag is provided, it
+    // will be overridden later.
+    imageName: '',
   };
 
   log(`Project root: ${info.root}`, true);
@@ -231,15 +244,16 @@ const readProjectInfo = async function (optionInfo) {
 
   // 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.
+  // Next if `--branch` flag and 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;
+  info.imageName = info.imageName || getImageName(info.activeBranchName);
 
   log(`Active image name: ${info.imageName}`, true);
   log(`Active vendor directory: ${info.vendorDirectory}`, true);
   log(`Active vendor strategy: ${info.vendorStrategy}`, true);
+  log(`Active branch: ${info.activeBranchName}`, true);
 
   return info;
 };

package/modules/utils.js

@@ -137,29 +137,9 @@ async function runGitMaybeHost(libdragonInfo, params, options = {}) {
   try {
     const isWin = /^win/.test(process.platform);
 
-    // When using host's git the actual top level can be higher in the tree
-    // rather that at the root of the project. We need to find it to run some
-    // git operations like subtree.
-    const gitRoot = (
-      await spawnProcess(
-        'git',
-        ['-C', libdragonInfo.root, 'rev-parse', '--show-toplevel'],
-        { inheritStdin: false }
-      ).catch(() => {
-        // Either this is not a git repo or the host does not have git
-        // We might also screw something up but we can live with it for now
-        return '';
-      })
-    ).trim();
-
     return await spawnProcess(
       'git',
-      [
-        '-C',
-        libdragonInfo.root,
-        ...(gitRoot ? ['--git-dir', `${gitRoot}/.git`] : []),
-        ...params,
-      ],
+      ['-C', libdragonInfo.root, ...params],
       // Windows git is breaking the TTY somehow - disable TTY for now
       // We are not able to display progress for the initial clone b/c of this
       // Enable progress otherwise.
@@ -287,7 +267,11 @@ async function initGitAndCacheContainerId(libdragonInfo) {
  */
 async function ensureGit(info) {
   const gitRoot = (
-    await runGitMaybeHost(info, ['rev-parse', '--show-toplevel']).catch(() => {
+    await runGitMaybeHost(info, ['rev-parse', '--show-toplevel'], {
+      inheritStdin: false,
+      inheritStdout: false,
+      inheritStderr: false,
+    }).catch(() => {
       // Probably host does not have git, can ignore
       return '';
     })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libdragon",
-  "version": "11.1.2",
+  "version": "11.2.0",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {
@@ -17,10 +17,10 @@
     "start": "node index.js start",
     "stop": "node index.js stop",
     "pack": "pkg ./",
-    "format": "prettier **/*.js --write",
-    "format-check": "prettier **/*.js --check",
-    "lint": "eslint --fix **/*.js",
-    "lint-check": "eslint **/*.js",
+    "format": "prettier **/*.js **/*.mjs **/*.cjs --write",
+    "format-check": "prettier **/*.js **/*.mjs **/*.cjs --check",
+    "lint": "eslint --fix modules/**/*.js *.js *.mjs *.cjs",
+    "lint-check": "eslint modules/**/*.js *.js *.mjs *.cjs",
     "tsc": "tsc"
   },
   "repository": {
@@ -40,7 +40,8 @@
   "dependencies": {
     "chalk": "^4.1.0",
     "command-line-usage": "^6.1.1",
-    "lodash": "^4.17.20"
+    "lodash": "^4.17.20",
+    "zx": "^8.1.8"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.1",
@@ -51,17 +52,12 @@
     "commitizen": "^4.2.4",
     "cz-conventional-changelog": "^3.3.0",
     "ed64": "^2.0.4",
-    "eslint": "^7.32.0",
+    "eslint": "^9.11.0",
     "jest": "^29.5.0",
     "pkg": "^5.5.2",
     "prettier": "^2.4.0",
-    "ref-napi": "^3.0.3",
-    "semantic-release": "^21.0.9",
-    "typescript": "^4.7.4",
-    "zx": "^7.2.2"
-  },
-  "overrides": {
-    "minimist": "1.2.6"
+    "semantic-release": "^24.0.0",
+    "typescript": "^4.7.4"
   },
   "pkg": {
     "targets": [