libdragon 10.7.1 → 10.8.1

package/README.md

@@ -2,11 +2,64 @@
 
 [![Build](https://github.com/anacierdem/libdragon-docker/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/anacierdem/libdragon-docker/actions/workflows/ci.yml)
 
-This is a wrapper for a docker container to make managing the libdragon toolchain easier.
+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.
 
-## Quick Install
+## Prerequisites
 
-On a system with [docker](https://www.docker.com/products/docker-desktop) (`>= 18`), grab a [pre-built executable](https://github.com/anacierdem/libdragon-docker/releases/latest) and put it somewhere on your PATH. Then navigate to the folder you want to initialize your project and invoke libdragon;
+You should have [docker](https://www.docker.com/products/docker-desktop) (`>= 18`) 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:
+
+### pre-built
+
+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</summary>
+
+  - Download the 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`
+  - Restart your computer.
+  - You should now be able to use the `libdragon` on a command line or PowerShell.
+  - To update it with a new version, just replace the file in `C:\bin`
+
+</details>
+
+<details>
+  <summary>MacOS instructions</summary>
+
+  - Download the 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.
+  - To update it with a new version, replace the file in `/usr/local/bin` and repeat the other steps.
+
+</details>
+
+<details>
+  <summary>Linux instructions</summary>
+
+  - You should already know this :)
+
+</details>
+
+### via NPM
+
+Install [node.js](https://nodejs.org/en/download/) (`>= 14`) and install `libdragon` as a global NPM package;
+
+    npm install -g libdragon
+
+To update the tool to the latest, do `npm i -g libdragon@latest`.
+
+## Quick Guide
+
+Navigate to the folder you want to initialize your project and invoke libdragon;
 
     libdragon init
 
@@ -22,21 +75,60 @@ To update the library and rebuild/install all the artifacts;
 
     libdragon update
 
-`git` is not strictly required to use this tool as docker's git will be used instead. Still, it is highly recommended to have git on your host machine.
+In general, you can invoke libdragon as follows;
 
-## Overall usage
+    libdragon [flags] <action>
 
-This is primarily a node.js script which is also packaged as an executable. If you have [node.js](https://nodejs.org/en/download/) (`>= 14`), you can do a global install and use it as usual. To install `libdragon` as a global NPM package;
+Run `libdragon help [action]` for more details on individual actions.
 
-    npm install -g libdragon
+## Recipes
 
-To update the tool to the latest, do `npm i -g libdragon@latest`.
+### Using a different branch of libdragon
 
-You can invoke libdragon as follows;
+Initialize your project as usual:
 
-    libdragon [flags] <action>
+    libdragon init
 
-Run `libdragon help [action]` for more details on individual actions.
+Then switch the submodule to the desired branch:
+
+    cd ./libdragon
+    git checkout opengl
+    cd ..
+    libdragon install
+
+If your changes are on a different remote, then you will need to manage your git remotes as usual.
+
+### Testing changes on libdragon
+
+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:
+
+    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:
+
+```makefile
+libdragon-install: libdragon
+	$(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.
+
+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.**
+
+To be able to share your project with the library change, you would need to push it somewhere public and make sure it is cloned properly by your contributors. This is not recommended for keeping track of your changes but is very useful if you plan to contribute it back to upstream. In the latter case, you can push your submodule branch to your fork and easily open a PR.
+
+#### **Using `subtree` vendor strategy.**
+
+To be able to share your project with the library change, you just commit your changes. This is very useful for keeping track of your changes specific to your project. On the other hand this is not recommended if you plan to contribute it back to upstream because you will need to make sure your libdragon commits are isolated and do the juggling when pushing it somewhere via `git subtree push`.
 
 ## Working on this repository
 
@@ -86,15 +178,40 @@ This repository also uses [ed64](https://github.com/anacierdem/ed64), so you can
 
 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`).
 
+### 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;
+
+    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.
+
+When you are happy with your changes, you can verify you conform to the coding standards via:
+
+    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 if your types, run:
+
+    npm run tsc
+
+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:
+
+    npx cz
+
+It will create a `semantic-release` compatible commit from your current staged changes.
+
 ## 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;
 
-    "scripts": {
-        "prepare": "libdragon init"
-        "build": "libdragon make",
-        "clean": "libdragon make clean"
-    }
+```json
+"scripts": {
+    "prepare": "libdragon init"
+    "build": "libdragon make",
+    "clean": "libdragon make clean"
+}
+```
 
 See [here](https://github.com/anacierdem/ed64-example) for a full example.
 
@@ -104,25 +221,32 @@ You can make an NPM package that a `libdragon` project can depend on. Just inclu
 
 For example this `package.json` in the dependent project;
 
-    {
-        "name": "libdragonDependentProject",
-        "version": "1.0.0",
-        "description": "...",
-        "scripts": {
-            "build": "libdragon make",
-            "clean": "libdragon make clean",
-            "prepare": "libdragon init"
-        },
-        "dependencies": {
-            "libdragon": <version>,
-            "ed64": <version>
-        }
+```json
+{
+    "name": "libdragonDependentProject",
+    "version": "1.0.0",
+    "description": "...",
+    "scripts": {
+        "build": "libdragon make",
+        "clean": "libdragon make clean",
+        "prepare": "libdragon init"
+    },
+    "dependencies": {
+        "libdragon": <version>,
+        "ed64": <version>
     }
+}
+```
 
 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.
 
+## TODOS
+
+- [ ] Skip CI checks for irrelevant changes.
+- [ ] Verify the NPM dependency mechanism is still working and add a test.
+
 ## Funding
 
 If this tool helped you, consider supporting its development by sponsoring it!

package/modules/actions/destroy.js

@@ -6,6 +6,9 @@ const { CONFIG_FILE, LIBDRAGON_PROJECT_MANIFEST } = require('../constants');
 const { fileExists, dirExists, log } = require('../helpers');
 const chalk = require('chalk');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const destroy = async (libdragonInfo) => {
   await destroyContainer(libdragonInfo);
 
@@ -22,13 +25,13 @@ const destroy = async (libdragonInfo) => {
   log(chalk.green('Done cleanup.'));
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'destroy',
   fn: destroy,
-  mustHaveProject: false,
+  forwardsRestParams: false,
   usage: {
     name: 'destroy',
     summary: 'Do clean-up for current project.',
     description: `Removes libdragon configuration from current project and removes any known containers but will not touch previously vendored files. \`libdragon\` will not work anymore for this project.`,
   },
-};
+});

package/modules/actions/disasm.js

@@ -10,6 +10,11 @@ const {
   ParameterError,
 } = require('../helpers');
 
+/**
+ * @param {string} stop
+ * @param {string} start
+ * @return {Promise<string>}
+ */
 const findElf = async (stop, start = '.') => {
   start = path.resolve(start);
 
@@ -43,6 +48,9 @@ const findElf = async (stop, start = '.') => {
   }
 };
 
+/**
+ * @param {import('../project-info').LibdragonInfo} info
+ */
 const disasm = async (info) => {
   let elfPath;
   if (info.options.FILE) {
@@ -89,7 +97,7 @@ const disasm = async (info) => {
   });
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'disasm',
   fn: disasm,
   forwardsRestParams: true,
@@ -118,4 +126,4 @@ module.exports = {
       },
     ],
   },
-};
+});

package/modules/actions/docker-utils.js

@@ -1,3 +1,8 @@
+/**
+ *
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @returns
+ */
 function dockerHostUserParams(libdragonInfo) {
   const { uid, gid } = libdragonInfo.userInfo;
   return ['-u', `${uid >= 0 ? uid : ''}:${gid >= 0 ? gid : ''}`];

package/modules/actions/exec.js

@@ -14,6 +14,10 @@ const { start } = require('./start');
 const { dockerHostUserParams } = require('./docker-utils');
 const { installDependencies } = require('./utils');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @returns
+ */
 function dockerRelativeWorkdir(libdragonInfo) {
   return (
     CONTAINER_TARGET_PATH +
@@ -22,10 +26,20 @@ function dockerRelativeWorkdir(libdragonInfo) {
   );
 }
 
+/**
+ *
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @returns
+ */
 function dockerRelativeWorkdirParams(libdragonInfo) {
   return ['--workdir', dockerRelativeWorkdir(libdragonInfo)];
 }
 
+/**
+ *
+ * @param {import('../project-info').LibdragonInfo} info
+ * @returns
+ */
 const exec = async (info) => {
   const parameters = info.options.EXTRA_PARAMS.slice(1);
   log(
@@ -37,6 +51,7 @@ const exec = async (info) => {
 
   const stdin = new PassThrough();
 
+  /** @type {string[]} */
   const paramsWithConvertedPaths = parameters.map((item) => {
     if (item.startsWith('-')) {
       return item;
@@ -49,9 +64,14 @@ const exec = async (info) => {
     return item;
   });
 
+  /**
+   *
+   * @param {import('../project-info').LibdragonInfo} libdragonInfo
+   * @param {import('../helpers').SpawnOptions} opts
+   * @returns
+   */
   const tryCmd = (libdragonInfo, opts = {}) => {
     const enableTTY = Boolean(process.stdout.isTTY && process.stdin.isTTY);
-
     return (
       libdragonInfo.containerId &&
       dockerExec(
@@ -80,6 +100,11 @@ const exec = async (info) => {
   };
 
   let started = false;
+  /**
+   *
+   * @param {import('fs').ReadStream=} stdin
+   * @returns
+   */
   const startOnceAndCmd = async (stdin) => {
     if (!started) {
       const newId = await start(info);
@@ -121,7 +146,11 @@ const exec = async (info) => {
       inheritStderr: false,
       // In the first run, pass the stdin to the process if it is not a TTY
       // o/w we loose a user input unnecesarily somehow.
-      stdin: !process.stdin.isTTY && process.stdin,
+      stdin:
+        !process.stdin.isTTY &&
+        /** @type {import('fs').ReadStream} */ (
+          /** @type {unknown} */ (process.stdin)
+        ),
     });
   } catch (e) {
     if (
@@ -131,12 +160,14 @@ const exec = async (info) => {
     ) {
       throw e;
     }
-    await startOnceAndCmd(stdin);
+    await startOnceAndCmd(
+      /** @type {import('fs').ReadStream} */ (/** @type {unknown} */ (stdin))
+    );
   }
   return info;
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'exec',
   fn: exec,
   forwardsRestParams: true,
@@ -152,4 +183,4 @@ module.exports = {
     
     Must be run in an initialized libdragon project.`,
   },
-};
+});

package/modules/actions/help.js

@@ -3,7 +3,10 @@ const commandLineUsage = require('command-line-usage');
 
 const { print } = require('../helpers');
 
-const printUsage = (info) => {
+/**
+ * @param {import('../project-info').CLIInfo} info
+ */
+const printUsage = async (info) => {
   const actions = require('./');
   const globalOptionDefinitions = [
     {
@@ -39,7 +42,7 @@ const printUsage = (info) => {
 
         To disable auto-vendoring, init with \`manual\`. With \`manual\`, libdragon files are expected at the location provided by \`--directory\` flag and the user is responsible for vendoring and updating them. This will allow using any other manual vendoring method.
 
-        You can always switch to manual by re-running \`init\` with \`--strategy manual\`, though you will be responsible for managing the existing submodule/subtree. Also it is not possible to automatically switch back.
+        You can always switch strategy by re-running \`init\` with \`--strategy\`, though you will be responsible for handling the old vendored files as they will be kept as is.
 
         With the \`manual\` strategy, it is still recommended to have a git repository at project root such that container actions can execute faster by caching the container id inside the \`.git\` folder.\n`,
       alias: 's',
@@ -48,11 +51,12 @@ const printUsage = (info) => {
     },
   ];
 
-  const actionsToShow =
+  const actionsToShow = /** @type {(keyof actions)[]} */ (
     info?.options.EXTRA_PARAMS?.filter(
       (action) =>
         Object.keys(actions).includes(action) && !['help'].includes(action)
-    ) ?? (info ? [info.options.CURRENT_ACTION.name] : []);
+    ) ?? (info ? [info.options.CURRENT_ACTION.name] : [])
+  );
 
   const sections = [
     {
@@ -96,13 +100,12 @@ const printUsage = (info) => {
   print(usage);
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'help',
   fn: printUsage,
   forwardsRestParams: true,
-  mustHaveProject: false,
   usage: {
     name: 'help [action]',
     summary: 'Display this help information or details for the given action.',
   },
-};
+});