libdragon 12.1.0 → 12.2.1

package/README.md

@@ -5,7 +5,7 @@
 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.
+> 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 giving devcontainers a try instead. It is doing a very similar thing. See the [template](https://github.com/anacierdem/libdragon-template) to get up and running.
 
 ## Prerequisites
 
@@ -69,7 +69,7 @@ Download the [pre-built executable](https://github.com/anacierdem/libdragon-dock
 
 ### 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
@@ -114,10 +114,10 @@ Run `libdragon help [action]` for more details on individual actions.
 Use the `--branch` flag to set up a custom libdragon branch when initializing your project:
 
 ```bash
-libdragon init --branch unstable
+libdragon init --branch preview
 ```
 
-This will use the `unstable` toolchain and code.
+This will use the `preview` toolchain and code.
 
 ### Switching to a different branch of libdragon
 
@@ -146,17 +146,6 @@ 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 automatically re-build the library by making it a make dependency in your project:
-
-```makefile
-libdragon-install:
-	$(MAKE) -C ./libdragon install
-```
-
-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.
-
-If you clone this repository, this setup is pretty much ready for you. Make sure you have a working libdragon setup and you get the submodules (e.g `git submodule update --init`). Then you can run `libdragon make bench` to execute the code in `./src` with your library changes. Also see [test bench](#local-test-bench).
-
 When managing your changes to the library, you have a few options:
 
 #### **Using `submodule` vendor strategy.**
@@ -170,9 +159,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.
+> You can simply use [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;
+After cloning this repository on a system with node.js (or devcontainer) & docker, in this repository's root do;
 
 ```bash
 npm install
@@ -190,35 +179,13 @@ Then run;
 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.
+to download the pre-built toolchain image, start and initialize it.
 
 Now you will be able to work on the files simultaneously with the docker container and any built binaries will be available in your workspace as it is mounted on the container.
 
-There is a root `Makefile` making deeper makefiles easier with these recipes;
-
-    bench: build the test bench (see below)
-    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
-```
-
-Similarly to run the `clean` recipe, run;
-
-```bash
-npm run libdragon -- make clean
-```
-
 > [!IMPORTANT]
 > Keep in mind that `--` is necessary for actual arguments when using npm scripts.
 
-
 To update the submodule and re-build everything;
 
 ```bash
@@ -227,20 +194,16 @@ npm run libdragon -- update
 
 ### Local test bench
 
-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 is a very barebones libdragon example in root `src` folder, called the test bench. You can build and clean it respectively with:
 
-There are also vscode launch configurations to quickly build and run the examples, tests and the bench. If you have [ares](https://ares-emu.net/) on your `PATH`, the launch configurations ending in `(emu)` will start it automatically. For the examples configuration, you can navigate to the relevant `.c` file and `Run selected example` will start it most of the time. In some cases, the output ROM name may not match the `.c` file and in those cases, you can select the ROM file instead and it should work.
-
-> [!NOTE]
-> This repository also uses [UNFLoader](https://github.com/buu342/N64-UNFLoader), so you can use the launch configurations without `(emu)` to run the code if you have a supported flashcart plugged in and have `UNFLoader` executable on your `PATH`.
->
-> The special `Debug Test Bench (emu)` configuration will start ares with remote debugging for the test bench if you have `gdb-multiarch` executable on your `PATH`. It should automatically break in your `main` function.
-
-You can clean everything with the `clean` recipe/task (open the command palette and choose `Run Task -> clean`).
+```bash
+npm run libdragon make -C ./src
+npm run libdragon make -C ./src 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;
+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
@@ -277,38 +240,19 @@ It will create a `semantic-release` compatible commit from your current staged c
 
 ### Devcontainer support
 
-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.
+The repository provides a devcontainer configuration for supported IDEs. If you have docker and a compatible IDE, you can quickly start working on this project.
+This has everything required to develop the tool itself. Just follow "Working on this repository" section inside the devcontainer.
 
 <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).
   - 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.
+> [!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.
 
 ## As an NPM dependency
 

package/modules/actions/help.js

@@ -16,6 +16,12 @@ const printUsage = async (info) => {
       alias: 'v',
       typeLabel: ' ',
     },
+    {
+      description:
+        'Execute the tool as if it is running in provided path on the host. Equivalent to `chdir`ing into that path.',
+      alias: 'C',
+      typeLabel: '<path>',
+    },
   ];
 
   const optionDefinitions = [

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,6 +1,6 @@
 {
   "name": "libdragon",
-  "version": "12.1.0",
+  "version": "12.2.1",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {
@@ -17,6 +17,7 @@
     "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",