libdragon 12.0.4 → 12.2.0

package/README.md

@@ -4,6 +4,9 @@
 
 This is a wrapper for a docker container to make managing the libdragon toolchain easier. It has the additional advantage that libdragon toolchain and library can be installed on a per-project basis instead of managing system-wide installations.
 
+> [!NOTE]
+> I've started this project a few years before [devcontainers](https://containers.dev/) were a thing. The cli still works and provides minor additional functionality, but if you already have a containerized environment, I suggest using a devcontainer instead. It is doing essentially the same thing. You can find more info in [`libdragon` devcontainer](#libdragon-configuration) section. I'll continue to improve that configuration to make it a compelling alternative.
+
 ## Prerequisites
 
 You should have [docker](https://www.docker.com/products/docker-desktop) (`>= 27.2.0`) and [git](https://git-scm.com/downloads) installed on your system.
@@ -33,7 +36,7 @@ Download the [pre-built executable](https://github.com/anacierdem/libdragon-dock
 <details>
   <summary>Windows instructions</summary>
 
-  - Download the Windows executable and copy it to `C:\bin`
+  - Download Windows executable and copy it to `C:\bin`
   - Press `Windows + R` key combination and then enter `rundll32 sysdm.cpl,EditEnvironmentVariables`
   - In the `Environment Variables` window find the `Path` variable under `User variables for <your user name>`
   - Double click it and add a new entry as `C:\bin`
@@ -46,7 +49,7 @@ Download the [pre-built executable](https://github.com/anacierdem/libdragon-dock
 <details>
   <summary>MacOS instructions</summary>
 
-  - Download the MacOS executable and copy it to `/usr/local/bin`
+  - Download MacOS executable and copy it to `/usr/local/bin`
   - Right click it and choose `Open`.
   - It will show a warning, approve it by clicking `Open` again. You can close the newly opened terminal window.
   - You should now be able to use the `libdragon` command.
@@ -57,13 +60,16 @@ Download the [pre-built executable](https://github.com/anacierdem/libdragon-dock
 <details>
   <summary>Linux instructions</summary>
 
-  - You should already know this :)
+  - Download Linux executable and copy it to `~/.local/bin`, or somewhere convenient on your `PATH`.
+  - Run `chmod u+x ~/.local/bin/libdragon`
+  - You should now be able to use the `libdragon` command on new shell sessions.
+  - To update it with a new version, replace the file and repeat the other steps.
 
 </details>
 
 ### via NPM
 
-Install [node.js](https://nodejs.org/en/download/) (`>= 22`) and install `libdragon` as a global NPM package;
+Install [node.js](https://nodejs.org/en/download/) (`>= 24`) and install `libdragon` as a global NPM package;
 
 ```bash
 npm install -g libdragon
@@ -163,7 +169,10 @@ 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 (`>= 27.2.0`), in this repository's root do;
+> [!TIP]
+> You can simply use [`development` devcontainer](#development-configuration) support to get up an running quickly if your development environment supports it.
+
+After cloning this repository on a system with node.js (`>= 24`) & docker (`>= 27.2.0`), in this repository's root do;
 
 ```bash
 npm install
@@ -237,7 +246,7 @@ For a quick development loop it really helps linking the code in this repository
 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).
+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.
 
 When you are happy with your changes, you can verify you conform to the coding standards via:
 
@@ -261,34 +270,49 @@ 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
+npm run cz
 ```
 
 It will create a `semantic-release` compatible commit from your current staged changes.
 
-### Experimental devcontainer support
-
-The repository provides a configuration (in `.devcontainer`) so that IDEs that support it can create and run the Docker container for you. Then, you can start working on it as if you are working on a machine with libdragon installed.
-
-With the provided setup, you can continue using the cli in the container and it will work for non-container specific actions like `install`, `disasm` etc. You don't have to use the cli in the container, but you can. In general it will be easier and faster to just run `make` in the container but this setup is included to ease developing the cli as well.
-
-To create your own dev container backed project, you can use the contents of the `.devcontainer` folder as reference. You don't need to include nodejs or the cli and you can just run `build.sh` as `postCreateCommand`. See the `devcontainer.json` for more details. As long as your container have the `DOCKER_CONTAINER` environment variable, the tool can work inside a container.
+### Devcontainer support
 
-#### Caveats
-
-- In the devcontainer, uploading via USB will not work.
-- Error matching is not yet tested.
-- Ideally the necessary extensions should be automatically installed. This is not configured yet.
+The repository provides two devcontainer configurations (`development` and `libdragon`) for supported IDEs. If you have docker and a compatible IDE, you can quickly start working on this project.
+To create your own dev container backed project, you can use the contents of the `.devcontainer` folder as reference.
 
 <details>
   <summary>vscode instructions</summary>
 
   - Make sure you have the [Dev container extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) installed and you fulfill its [requirements](https://code.visualstudio.com/docs/devcontainers/containers).
-  - Clone this repository with `--recurse-submodules` or run `git submodule update --init`.
   - Open command palette and run `Dev Containers: Reopen in container`.
+  - Pick `development` or `libdragon` configuration.
   - It will prepare the container and open it in the editor.
 </details>
 
+#### `development` configuration
+
+This has everything required to develop the tool itself. Just follow "Working on this repository" section inside the devcontainer.
+
+> [!NOTE]
+> When working in this devcontainer on a Linux host, you can build and install the latest executable in `${HOME}/.local/bin` by running `npm run install-host` (in the container) to test it on your host.
+
+#### `libdragon` configuration
+
+This is an example devcontainer setup for using the libdragon toolchain to build n64 ROMs. To start building with libdragon:
+
+- Clone this repository with `--recurse-submodules` or run `git submodule update --init` in the devcontainer.
+- Run `cd libdragon && ./build.sh && cd ..` to build and install the library.
+- Run `make bench` to build the [test bench](#local-test-bench). You'll see the rom in `src` folder.
+
+If you setup a similar devcontainer for your project, you can immediately start building n64 ROMs using libdragon.
+
+#### Future direction
+
+- The cli is not enabled on `libdragon` devcontainer, so you cannot currently use actions like `install` or `disasm`. This is supported by the cli (via `DOCKER_CONTAINER`) but not yet enabled on the devcontainer.
+- In the devcontainer, uploading via USB is not yet implemented.
+- Error matching is not yet tested.
+- Ideally the necessary extensions should be automatically installed. This is not configured yet.
+
 ## 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 installation is provided that can be used in your NPM scripts as follows;

package/modules/actions/start.js

@@ -39,6 +39,7 @@ const initContainer = async (libdragonInfo) => {
           ',target=' +
           CONTAINER_TARGET_PATH, // Mount files
         '-w=' + CONTAINER_TARGET_PATH, // Set working directory
+        "--add-host=host.docker.internal:host-gateway",
         libdragonInfo.imageName,
         'tail',
         '-f',

package/modules/parameters.js

@@ -20,6 +20,7 @@ const { globals } = require('./globals');
  *  VENDOR_STRAT?: VendorStrategy;
  *  FILE?: string;
  *  BRANCH?: string;
+ *  CWD?: string;
  * }} CommandlineOptions
  */
 
@@ -33,6 +34,9 @@ const parseParameters = async (argv) => {
     CURRENT_ACTION: undefined,
   };
 
+  /** @type string[] */
+  let potentialExtraFlags = [];
+
   for (let i = 2; i < argv.length; i++) {
     const val = argv[i];
 
@@ -90,9 +94,15 @@ const parseParameters = async (argv) => {
       continue;
     }
 
+    if (['-C'].includes(val)) {
+      options.CWD = argv[++i];
+      continue;
+    }
+
+    // Collect unknown flags
     if (val.indexOf('-') == 0) {
-      log(chalk.red(`Invalid flag \`${val}\``));
-      process.exit(STATUS_BAD_PARAM);
+      potentialExtraFlags.push(val);
+      continue;
     }
 
     if (options.CURRENT_ACTION) {
@@ -126,6 +136,20 @@ const parseParameters = async (argv) => {
     process.exit(STATUS_BAD_PARAM);
   }
 
+  // Because of https://github.com/microsoft/vscode-cpptools/issues/14169
+  // move any unkown flags before the action to the end of the container command
+  if (
+    options.CURRENT_ACTION !== actions.exec &&
+    potentialExtraFlags.length > 0
+  ) {
+    log(chalk.red(`Invalid flag \`${potentialExtraFlags[0]}\``));
+    process.exit(STATUS_BAD_PARAM);
+  }
+
+  if (options.CURRENT_ACTION === actions.exec) {
+    options.EXTRA_PARAMS = [...options.EXTRA_PARAMS, ...potentialExtraFlags];
+  }
+
   if (
     !(
       /** @type {typeof actions[keyof actions][]} */ ([

package/modules/project-info.js

@@ -165,6 +165,8 @@ const readProjectInfo = async function (optionInfo) {
     return /** @type {NoProjectInfo} */ (optionInfo);
   }
 
+  optionInfo.options.CWD && process.chdir(optionInfo.options.CWD);
+
   const projectRoot = await findLibdragonRoot();
 
   if (

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "libdragon",
-  "version": "12.0.4",
+  "version": "12.2.0",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {
-    "node": ">=22",
+    "node": ">=24",
     "npm": ">=10"
   },
   "bin": {
@@ -17,12 +17,14 @@
     "start": "node index.js start",
     "stop": "node index.js stop",
     "pack": "node pack.mjs",
+    "install-host": "node pack.mjs --install",
     "bundle": "node bundle.mjs",
     "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"
+    "tsc": "tsc",
+    "cz": "cz"
   },
   "repository": {
     "type": "git",
@@ -39,29 +41,24 @@
   },
   "homepage": "https://github.com/anacierdem/libdragon-docker#readme",
   "dependencies": {
-    "chalk": "^4.1.0",
-    "command-line-usage": "^6.1.1",
-    "zx": "^8.1.8"
+    "chalk": "^4.1.2",
+    "command-line-usage": "^6.1.3",
+    "zx": "^8.8.5"
   },
   "devDependencies": {
-    "@semantic-release/changelog": "^6.0.1",
-    "@semantic-release/exec": "^6.0.3",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
-    "@types/command-line-usage": "^5.0.2",
-    "commitizen": "^4.2.4",
+    "@types/command-line-usage": "^5.0.4",
     "cz-conventional-changelog": "^3.3.0",
-    "esbuild": "^0.20.0",
-    "eslint": "^9.11.0",
-    "jest": "^29.5.0",
+    "esbuild": "^0.25.12",
+    "eslint": "^9.39.2",
+    "jest": "^29.7.0",
     "postject": "^1.0.0-alpha.6",
-    "prettier": "^2.4.0",
-    "ref-napi": "^3.0.3",
-    "semantic-release": "^24.0.0",
-    "typescript": "^4.7.4",
-    "zx": "^8.1.8"
-  },
-  "overrides": {
-    "minimist": "1.2.6"
+    "prettier": "^2.8.8",
+    "semantic-release": "^25.0.3",
+    "typescript": "^4.9.5",
+    "zx": "^8.8.5"
   },
   "release": {
     "plugins": [