libdragon 12.0.3 → 12.1.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,7 +60,10 @@ 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>
 
@@ -163,6 +169,9 @@ To be able to share your project with the library change, you just commit your c
 
 ## Working on this repository
 
+> [!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 (`>= 18`) & docker (`>= 27.2.0`), in this repository's root do;
 
 ```bash
@@ -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,46 @@ 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.
+### Devcontainer support
 
-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.
-
-#### 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.
+
+#### `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

@@ -34,13 +34,13 @@ const initContainer = async (libdragonInfo) => {
         'run',
         '-d', // Detached
         '--mount',
-        '"type=bind,source=' +
+        'type=bind,source=' +
           libdragonInfo.root +
           ',target=' +
-          CONTAINER_TARGET_PATH +
-          '"', // Mount files
-        '"-w=' + CONTAINER_TARGET_PATH + '"', // Set working directory
-        '"' + libdragonInfo.imageName + '"',
+          CONTAINER_TARGET_PATH, // Mount files
+        '-w=' + CONTAINER_TARGET_PATH, // Set working directory
+        "--add-host=host.docker.internal:host-gateway",
+        libdragonInfo.imageName,
         'tail',
         '-f',
         '/dev/null',
@@ -59,12 +59,7 @@ const initContainer = async (libdragonInfo) => {
         '-R',
         `${uid >= 0 ? uid : ''}:${gid >= 0 ? gid : ''}`,
         '/n64_toolchain',
-      ],
-      {
-        spawnOptions: {
-          shell: true,
-        },
-      }
+      ]
     );
   } catch (e) {
     // Dispose the invalid container, clean and exit

package/modules/helpers.js

@@ -124,12 +124,11 @@ async function dirExists(path) {
  * }} SpawnOptions
  */
 
+// A simple Promise wrapper for child_process.spawn. Return the err/out streams
+// from the process by default. Specify inheritStdout / inheritStderr to disable
+// this and inherit the parent process's stream, passing through the TTY if any.
 /**
- * A simple Promise wrapper for child_process.spawn. Return the err/out streams
- * from the process by default. Specify inheritStdout / inheritStderr to disable
- * this and inherit the parent process's stream, passing through the TTY if any.
- * Runs everything in a shell, so be careful with user input. By default, we get
- * the input from user but this is the whole idea of most of the logic here.
+ *
  * @param {string} cmd
  * @param {string[]} params
  * @param {SpawnOptions} options
@@ -185,15 +184,10 @@ function spawnProcess(
         enableErrorTTY ? 'inherit' : 'pipe',
       ],
       env: {
+        ...process.env,
         // Prevent the annoying docker "What's next?" message. It messes up everything.
         DOCKER_CLI_HINTS: 'false',
       },
-      // On macos, we need to run the command in a shell for some docker commands
-      // to work properly. The ones with paths in them probably not working on
-      // macOS. No need to do this on Windows, as it'd now require additional
-      // escaping for the paths.
-      // shell: process.platform === 'darwin',
-      shell: true,
       ...spawnOptions,
     });
 
@@ -320,7 +314,6 @@ const dockerExec = /** @type {DockerExec} */ (
         ...options,
         spawnOptions: {
           cwd: workDir,
-          shell: false,
           ...options?.spawnOptions,
         },
       });

package/modules/npm-utils.js

@@ -21,7 +21,16 @@ async function findNPMRoot() {
 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/project-info.js

@@ -91,7 +91,7 @@ async function findContainerId(libdragonInfo) {
       '--format',
       '{{.}}{{.ID}}',
       '-f',
-      '"volume=' + CONTAINER_TARGET_PATH + '"',
+      'volume=' + CONTAINER_TARGET_PATH,
     ])
   )
     .split('\n')

package/modules/utils.js

@@ -40,12 +40,7 @@ const installDependencies = async (libdragonInfo) => {
       CONTAINER_TARGET_PATH + '/' + libdragonInfo.vendorDirectory,
       ...dockerHostUserParams(libdragonInfo),
     ],
-    ['/bin/bash', './build.sh'],
-    {
-      spawnOptions: {
-        shell: true,
-      },
-    }
+    ['/bin/bash', './build.sh']
   );
 };
 
@@ -138,7 +133,7 @@ async function runGit(libdragonInfo, params, options = {}) {
 
   return await spawnProcess(
     'git',
-    ['-C', '"' + libdragonInfo.root + '"', ...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.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "libdragon",
-  "version": "12.0.3",
+  "version": "12.1.0",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {
-    "node": ">=22",
+    "node": ">=24",
     "npm": ">=10"
   },
   "bin": {
@@ -22,7 +22,8 @@
     "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 +40,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": [