libdragon 10.4.2 → 10.5.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Change Log
 
+## [10.5.0] - 2022-04-09
+### Fixed
+
+- Fix a path bug that would cause incorrect behaviour when the command is run
+deeper than a single level in the project folder.
+- Fix a potential issue where `build.sh`might be incorrectly found inexistant
+if the OS is picky about the paths to have native separators.
+- Only save project information when necessary. Previously actions like `help`
+were saving project info mistakenly.
+
+### Added
+
+- `disasm` action to simplify disassembling ELF files generated by the toolchain.
+- `version` action to display current version.
+- `clean` action to remove the libdragon project.
+- Additional documentation for flags.
+- Print duration information when verbose.
+
+### Changed
+
+- Refactored out NPM related functions.
+- Moved usage parameters to respective actions files as a refactor.
+- It is possible to provide an absolute path to init `--directory` as long as it
+is inside the project directory. Previously it was possible to provide somewhere
+outside the project, but it would fail with an unexpected error.
+- Simplify saving mechanism. Each action now internally resolves into the data
+to save if any.
+
 ## [10.4.2] - 2022-04-03
 
 ### Fixed

package/index.js

@@ -15,6 +15,7 @@ const {
   CommandError,
   ParameterError,
   ValidationError,
+  log,
 } = require('./modules/helpers');
 const { readProjectInfo, writeProjectInfo } = require('./modules/project-info');
 
@@ -33,6 +34,7 @@ for (let i = 2; i < process.argv.length; i++) {
     continue;
   }
 
+  // TODO: we might move these to actions as well.
   if (['--image', '-i'].includes(val)) {
     options.DOCKER_IMAGE = process.argv[++i];
     continue;
@@ -57,6 +59,14 @@ for (let i = 2; i < process.argv.length; i++) {
     continue;
   }
 
+  if (['--file', '-f'].includes(val)) {
+    options.FILE = process.argv[++i];
+    continue;
+  } else if (val.indexOf('--file=') === 0) {
+    options.FILE = val.split('=')[1];
+    continue;
+  }
+
   if (val.indexOf('--') >= 0) {
     console.error(chalk.red(`Invalid flag \`${val}\``));
     printUsage();
@@ -115,6 +125,12 @@ if (
   process.exit(STATUS_BAD_PARAM);
 }
 
+if (![actions.disasm].includes(currentAction) && options.FILE) {
+  console.error(chalk.red('Invalid flag: file'));
+  printUsage(undefined, [currentAction.name]);
+  process.exit(STATUS_BAD_PARAM);
+}
+
 readProjectInfo()
   .then((info) =>
     currentAction.fn(
@@ -160,10 +176,9 @@ readProjectInfo()
     // We don't have a user targeted error anymore, we did a mistake for sure
     process.exit(STATUS_ERROR);
   })
-  .then(() => {
-    // Everything was done, update the configuration file if not exiting early
-    return writeProjectInfo();
-  })
+  // Everything was done, update the configuration file if not exiting early
+  .then(writeProjectInfo)
   .finally(() => {
+    log(`Took: ${process.uptime()}s`, true);
     process.exit(STATUS_OK);
   });

package/modules/actions/clean.js

@@ -0,0 +1,35 @@
+const fs = require('fs/promises');
+const path = require('path');
+
+const { mustHaveProject, destroyContainer } = require('./utils');
+const { CONFIG_FILE, LIBDRAGON_PROJECT_MANIFEST } = require('../constants');
+const { fileExists, dirExists } = require('../helpers');
+
+const clean = async (libdragonInfo) => {
+  await mustHaveProject(libdragonInfo);
+
+  await destroyContainer(libdragonInfo);
+
+  const projectPath = path.join(libdragonInfo.root, LIBDRAGON_PROJECT_MANIFEST);
+  const configPath = path.join(projectPath, CONFIG_FILE);
+
+  if (await fileExists(configPath)) {
+    await fs.rm(configPath);
+  }
+  if (dirExists(projectPath)) {
+    await fs.rmdir(projectPath);
+  }
+};
+
+module.exports = {
+  name: 'clean',
+  fn: clean,
+  showStatus: true,
+  usage: {
+    name: 'clean',
+    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.
+
+      Must be run in an initialized libdragon project.`,
+  },
+};

package/modules/actions/disasm.js

@@ -0,0 +1,116 @@
+const path = require('path');
+const fs = require('fs/promises');
+
+const { mustHaveProject } = require('./utils');
+const { fn: exec } = require('./exec');
+const {
+  ValidationError,
+  toPosixPath,
+  dirExists,
+  fileExists,
+  ParameterError,
+} = require('../helpers');
+
+const findElf = async (stop, start = '.') => {
+  start = path.resolve(start);
+
+  const files = await fs.readdir(start);
+
+  const buildDir = path.join(start, 'build');
+  if (await dirExists(buildDir)) {
+    const elfFile = await findElf(buildDir, buildDir);
+    if (elfFile) return elfFile;
+  }
+
+  const elfFiles = files.filter((name) => name.endsWith('.elf'));
+
+  if (elfFiles.length > 1) {
+    throw new ValidationError(
+      `Multiple ELF files found in ${path.resolve(
+        start
+      )}. Use --file to specify.`
+    );
+  }
+
+  if (elfFiles.length === 1) {
+    return path.join(start, elfFiles[0]);
+  }
+
+  const parent = path.join(start, '..');
+  if (start !== stop) {
+    return await findElf(stop, parent);
+  } else {
+    throw new ValidationError(`No ELF files found. Use --file to specify.`);
+  }
+};
+
+const disasm = async (libdragonInfo, extraArgs) => {
+  await mustHaveProject(libdragonInfo);
+
+  let elfPath;
+  if (libdragonInfo.options.FILE) {
+    if (
+      path
+        .relative(libdragonInfo.root, libdragonInfo.options.FILE)
+        .startsWith('..')
+    ) {
+      throw new ParameterError(
+        `Provided file ${libdragonInfo.options.FILE} is outside the project directory.`
+      );
+    }
+    if (!(await fileExists(libdragonInfo.options.FILE)))
+      throw new ParameterError(
+        `Provided file ${libdragonInfo.options.FILE} does not exist`
+      );
+    elfPath = libdragonInfo.options.FILE;
+  }
+  elfPath = elfPath ?? (await findElf(libdragonInfo.root));
+
+  const haveSymbol = extraArgs.length > 0 && !extraArgs[0].startsWith('-');
+
+  const finalArgs = haveSymbol
+    ? [`--disassemble=${extraArgs[0]}`, ...extraArgs.slice(1)]
+    : extraArgs;
+
+  const intermixSourceParams =
+    extraArgs.length === 0 || haveSymbol ? ['-S'] : [];
+
+  return await exec(libdragonInfo, [
+    'mips64-elf-objdump',
+    ...finalArgs,
+    ...intermixSourceParams,
+    toPosixPath(path.relative(process.cwd(), elfPath)),
+  ]);
+};
+
+module.exports = {
+  name: 'disasm',
+  fn: disasm,
+  showStatus: true,
+  forwardsRestParams: true,
+  usage: {
+    name: 'disasm [symbol|flags]',
+    summary: 'Disassemble the nearest *.elf file.',
+    description: `Executes \`objdump\` for the nearest *.elf file starting from the working directory, going up. If there is a \`build\` directory in the searched paths, checks inside it as well. Any extra flags are passed down to \`objdump\` before the filename.
+
+    If a symbol name is provided after the action, it is converted to \`--disassembly=<symbol>\` and intermixed source* (\`-S\`) is automatically applied. This allows disassembling a single symbol by running;
+
+    \`libdragon disasm main\`
+
+    Again, any following flags are forwarded down. If run without extra symbol/flags, disassembles whole ELF with \`-S\` by default.
+
+    Must be run in an initialized libdragon project.
+
+    * Note that to be able to see the source, the code must be built with \`D=1\``,
+
+    optionList: [
+      {
+        name: 'file',
+        description:
+          'Provide a specific ELF file relative to current working directory and inside the libdragon project.',
+        alias: 'f',
+        typeLabel: ' ',
+      },
+    ],
+  },
+};

package/modules/actions/docker-utils.js

@@ -0,0 +1,8 @@
+function dockerHostUserParams(libdragonInfo) {
+  const { uid, gid } = libdragonInfo.userInfo;
+  return ['-u', `${uid >= 0 ? uid : ''}:${gid >= 0 ? gid : ''}`];
+}
+
+module.exports = {
+  dockerHostUserParams,
+};

package/modules/actions/exec.js

@@ -4,11 +4,8 @@ const { CONTAINER_TARGET_PATH } = require('../constants');
 const { log, dockerExec, toPosixPath } = require('../helpers');
 
 const { start } = require('./start');
-const {
-  dockerHostUserParams,
-  installDependencies,
-  mustHaveProject,
-} = require('./utils');
+const { dockerHostUserParams } = require('./docker-utils');
+const { installDependencies, mustHaveProject } = require('./utils');
 
 function dockerRelativeWorkdir(libdragonInfo) {
   return (
@@ -72,7 +69,7 @@ const exec = async (libdragonInfo, commandAndParams) => {
   if (!libdragonInfo.containerId) {
     log(`Container does not exist for sure, restart`, true);
     await startOnceAndCmd();
-    return;
+    return libdragonInfo;
   }
 
   try {
@@ -87,6 +84,7 @@ const exec = async (libdragonInfo, commandAndParams) => {
     }
     await startOnceAndCmd();
   }
+  return libdragonInfo;
 };
 
 module.exports = {
@@ -94,4 +92,15 @@ module.exports = {
   fn: exec,
   forwardsRestParams: true,
   showStatus: true,
+  usage: {
+    name: 'exec <command>',
+    summary: 'Execute given command in the current directory.',
+    description: `Executes the given command in the container passing down any arguments provided. If you change your host working directory, the command will be executed in the corresponding folder in the container as well.
+
+    This action will first try to execute the command in the container and if the container is not accessible, it will attempt a complete \`start\` cycle.
+
+    This will properly passthrough your TTY if you have one. So by running \`libdragon exec bash\` you can start an interactive bash session with full TTY support.
+    
+    Must be run in an initialized libdragon project.`,
+  },
 };

package/modules/actions/help.js

@@ -4,6 +4,7 @@ const commandLineUsage = require('command-line-usage');
 const { log } = require('../helpers');
 
 const printUsage = (_, actionArr) => {
+  const actions = require('./');
   const globalOptionDefinitions = [
     {
       name: 'verbose',
@@ -11,7 +12,6 @@ const printUsage = (_, actionArr) => {
         'Be verbose. This will print all commands dispatched and their outputs as well. Will also start printing error stack traces.',
       alias: 'v',
       typeLabel: ' ',
-      group: 'global',
     },
   ];
 
@@ -26,7 +26,7 @@ const printUsage = (_, actionArr) => {
     },
     {
       name: 'directory',
-      description: `Directory where libdragon files are expected. It must be a project relative path as it will be mounted on the docker container. The cli will create and manage it when using a non-manual strategy. Defaults to \`./libdragon\` if not provided.\n`,
+      description: `Directory where libdragon files are expected. It must be inside the libdragon project as it will be mounted on the docker container. The cli will create and manage it when using a non-manual strategy. Defaults to \`./libdragon\` if not provided.\n`,
       alias: 'd',
       typeLabel: '<path>',
       group: 'vendoring',
@@ -48,72 +48,6 @@ const printUsage = (_, actionArr) => {
     },
   ];
 
-  // TODO: move these to respective actions
-
-  const actions = {
-    help: {
-      name: 'help [action]',
-      summary: 'Display this help information or details for the given action.',
-    },
-    init: {
-      name: 'init',
-      summary: 'Create a libdragon project in the current directory.',
-      description: `Creates a libdragon project in the current directory. Every libdragon project will have its own docker container instance. If you are in a git repository or an NPM project, libdragon will be initialized at their root also marking there with a \`.libdragon\` folder. Do not remove the \`.libdragon\` folder and commit its contents if you are using source control, as it keeps persistent libdragon project information.
-
-      By default, a git repository and a submodule at \`./libdragon\` will be created to automatically update the vendored libdragon files on subsequent \`update\`s. If you intend to opt-out from this feature, see the \`--strategy manual\` flag to provide your self-managed libdragon copy. The default behaviour is intended for users who primarily want to consume libdragon as is.
-
-      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, it will act like \`start\` thus can be used to revive an existing project without modifying it.`,
-      group: ['docker', 'vendoring'],
-    },
-    make: {
-      name: 'make [params]',
-      summary: 'Run the libdragon build system in the current directory.',
-      description: `Runs the libdragon build system in the current directory. It will mirror your current working directory to the container.
-
-      Must be run in an initialized libdragon project. This action is a shortcut to the \`exec\` action under the hood.`,
-    },
-    exec: {
-      name: 'exec <command>',
-      summary: 'Execute given command in the current directory.',
-      description: `Executes the given command in the container passing down any arguments provided. If you change your host working directory, the command will be executed in the corresponding folder in the container as well.
-
-      This action will first try to execute the command in the container and if the container is not accessible, it will attempt a complete \`start\` cycle.
-
-      This will properly passthrough your TTY if you have one. So by running \`libdragon exec bash\` you can start an interactive bash session with full TTY support.
-      
-      Must be run in an initialized libdragon project.`,
-    },
-    start: {
-      name: 'start',
-      summary: 'Start the container for current project.',
-      description: `Start the container assigned to the current libdragon project. Will first attempt to start an existing container if found, followed by a new container run and installation similar to the \`install\` action. Will always print out the container id on success.
-
-        Must be run in an initialized libdragon project.`,
-    },
-    name: {
-      name: 'stop',
-      summary: 'Stop the container for current project.',
-      description: `Stop the container assigned to the current libdragon project.
-
-        Must be run in an initialized libdragon project.`,
-    },
-    install: {
-      name: 'install',
-      summary: 'Vendor libdragon as is.',
-      description: `Attempts to build and install everything libdragon related into the container. This includes all the tools and third parties used by libdragon except for the toolchain. If you have made changes to libdragon, you can execute this action to build everything based on your changes. Requires you to have an intact vendoring target (also see the \`--directory\` flag). If you are not working on libdragon itself, you can just use the \`update\` action instead.
-
-      Must be run in an initialized libdragon project. This can be useful to recover from a half-baked container.`,
-    },
-    update: {
-      name: 'update',
-      summary: 'Update libdragon and do an install.',
-      description: `Will update the docker image and if you are using auto-vendoring (see \`--strategy\`), will also update the submodule/subtree from the remote branch (\`trunk\`) with a merge/squash strategy and then perform a \`libdragon install\`. You can use the \`install\` action to only update all libdragon related artifacts in the container.
-
-        Must be run in an initialized libdragon project.`,
-      group: ['docker'],
-    },
-  };
-
   const actionsToShow = actionArr
     ?.filter((action) => Object.keys(actions).includes(action))
     .filter((action) => !['help'].includes(action));
@@ -121,28 +55,33 @@ const printUsage = (_, actionArr) => {
   const sections = [
     {
       header: chalk.green('Usage:'),
-      content: 'libdragon [flags] <action>',
+      content: `libdragon [flags] <action>
+
+      For string flags valid syntax are: \`-i <value>\` or \`--image=<value>\``,
     },
     ...(actionsToShow?.length
       ? actionsToShow.flatMap((action) => [
           {
             header: chalk.green(`${action} action:`),
-            content: actions[action].description,
+            content: actions[action].usage.description,
           },
-          actions[action].group
+          actions[action].usage.group || actions[action].usage.optionList
             ? {
                 header: `accepted flags:`,
-                optionList: optionDefinitions,
-                group: actions[action].group,
+                optionList: [
+                  ...(actions[action].usage.group ? optionDefinitions : []),
+                  ...(actions[action].usage.optionList ?? []),
+                ],
+                group: actions[action].usage.group,
               }
             : {},
         ])
       : [
           {
             header: chalk.green('Available Commands:'),
-            content: Object.values(actions).map((action) => ({
-              name: action.name,
-              summary: action.summary,
+            content: Object.values(actions).map(({ usage }) => ({
+              name: usage.name,
+              summary: usage.summary,
             })),
           },
         ]),
@@ -160,4 +99,8 @@ module.exports = {
   fn: printUsage,
   showStatus: true,
   forwardsRestParams: true,
+  usage: {
+    name: 'help [action]',
+    summary: 'Display this help information or details for the given action.',
+  },
 };

package/modules/actions/index.js

@@ -1,25 +1,17 @@
-const { fn: exec } = require('./exec');
-
-const make = async (libdragonInfo, params) => {
-  await exec(libdragonInfo, ['make', ...params]);
-};
-
-// TODO: separate into files
 module.exports = {
   start: require('./start'),
   stop: require('./stop'),
   init: require('./init'),
 
   exec: require('./exec'),
-  make: {
-    name: 'make',
-    fn: make,
-    forwardsRestParams: true,
-    showStatus: true,
-  },
+  make: require('./make'),
+
+  disasm: require('./disasm'),
 
   install: require('./install'),
   update: require('./update'),
 
   help: require('./help'),
+  version: require('./version'),
+  clean: require('./clean'),
 };

package/modules/actions/init.js

@@ -24,8 +24,9 @@ const {
   CommandError,
   ParameterError,
   ValidationError,
+  toPosixPath,
+  toNativePath,
 } = require('../helpers');
-const { setProjectInfoToSave } = require('../project-info');
 
 const autoVendor = async (libdragonInfo) => {
   await runGitMaybeHost(libdragonInfo, ['init']);
@@ -111,25 +112,24 @@ async function init(libdragonInfo) {
 
   // Update the strategy information for the project if the flag is provided
   if (newInfo.options.VENDOR_STRAT) {
-    newInfo = setProjectInfoToSave({
-      ...newInfo,
-      vendorStrategy: newInfo.options.VENDOR_STRAT,
-    });
+    newInfo.vendorStrategy = newInfo.options.VENDOR_STRAT;
   }
 
   // Update the directory information for the project if the flag is provided
   if (newInfo.options.VENDOR_DIR) {
+    const relativeVendorDir = path.relative(
+      libdragonInfo.root,
+      libdragonInfo.options.VENDOR_DIR
+    );
     // Validate vendoring path
-    if (path.isAbsolute(newInfo.options.VENDOR_DIR)) {
+    if (relativeVendorDir.startsWith('..')) {
       throw new ParameterError(
-        '`--directory` must be project-relative as it will be mounted to the docker container.'
+        `\`--directory=${libdragonInfo.options.VENDOR_DIR}\` is outside the project directory.`
       );
     }
 
-    newInfo = setProjectInfoToSave({
-      ...newInfo,
-      vendorDirectory: newInfo.options.VENDOR_DIR,
-    });
+    // Immeditately convert it to a posix and relative path
+    newInfo.vendorDirectory = toPosixPath(relativeVendorDir);
   }
 
   if (newInfo.haveProjectConfig) {
@@ -145,12 +145,11 @@ async function init(libdragonInfo) {
       );
     }
     // TODO: we may make sure git and submodule is initialized here
-    await install(newInfo);
-    return;
+    return await install(newInfo);
   }
 
-  newInfo.imageName =
-    (await updateImage(newInfo, newInfo.imageName)) || newInfo.imageName;
+  await updateImage(newInfo, newInfo.imageName);
+
   // Download image and start it
   const containerReadyPromise = start(newInfo, true).then((newId) => ({
     ...newInfo,
@@ -159,7 +158,10 @@ async function init(libdragonInfo) {
 
   let vendorAndGitReadyPromise = containerReadyPromise;
   if (newInfo.vendorStrategy !== 'manual') {
-    const vendorTarget = path.relative(newInfo.root, newInfo.vendorDirectory);
+    const vendorTarget = path.relative(
+      newInfo.root,
+      toNativePath(newInfo.vendorDirectory)
+    );
     const [vendorTargetExists] = await Promise.all([
       fs.stat(vendorTarget).catch((e) => {
         if (e.code !== 'ENOENT') throw e;
@@ -171,8 +173,7 @@ async function init(libdragonInfo) {
     if (vendorTargetExists) {
       throw new ValidationError(
         `${path.resolve(
-          newInfo.root,
-          newInfo.vendorDirectory
+          vendorTarget
         )} already exists. That is the libdragon vendoring target, please remove and retry.`
       );
     }
@@ -192,10 +193,21 @@ async function init(libdragonInfo) {
   ]);
 
   log(chalk.green(`libdragon ready at \`${newInfo.root}\`.`));
+  return newInfo;
 }
 
 module.exports = {
   name: 'init',
   fn: init,
   showStatus: true,
+  usage: {
+    name: 'init',
+    summary: 'Create a libdragon project in the current directory.',
+    description: `Creates a libdragon project in the current directory. Every libdragon project will have its own docker container instance. If you are in a git repository or an NPM project, libdragon will be initialized at their root also marking there with a \`.libdragon\` folder. Do not remove the \`.libdragon\` folder and commit its contents if you are using source control, as it keeps persistent libdragon project information.
+
+    By default, a git repository and a submodule at \`./libdragon\` will be created to automatically update the vendored libdragon files on subsequent \`update\`s. If you intend to opt-out from this feature, see the \`--strategy manual\` flag to provide your self-managed libdragon copy. The default behaviour is intended for users who primarily want to consume libdragon as is.
+
+    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, it will act like \`start\` thus can be used to revive an existing project without modifying it.`,
+    group: ['docker', 'vendoring'],
+  },
 };

package/modules/actions/install.js

@@ -39,10 +39,18 @@ const install = async (libdragonInfo, skipUpdate) => {
   // Re-install vendors on new image
   // TODO: skip this if unnecessary
   await installDependencies(updatedInfo);
+  return updatedInfo;
 };
 
 module.exports = {
   name: 'install',
   fn: install,
   showStatus: true,
+  usage: {
+    name: 'install',
+    summary: 'Vendor libdragon as is.',
+    description: `Attempts to build and install everything libdragon related into the container. This includes all the tools and third parties used by libdragon except for the toolchain. If you have made changes to libdragon, you can execute this action to build everything based on your changes. Requires you to have an intact vendoring target (also see the \`--directory\` flag). If you are not working on libdragon itself, you can just use the \`update\` action instead.
+
+    Must be run in an initialized libdragon project. This can be useful to recover from a half-baked container.`,
+  },
 };

package/modules/actions/make.js

@@ -0,0 +1,19 @@
+const { fn: exec } = require('./exec');
+
+const make = async (libdragonInfo, params) => {
+  return await exec(libdragonInfo, ['make', ...params]);
+};
+
+module.exports = {
+  name: 'make',
+  fn: make,
+  forwardsRestParams: true,
+  showStatus: true,
+  usage: {
+    name: 'make [params]',
+    summary: 'Run the libdragon build system in the current directory.',
+    description: `Runs the libdragon build system in the current directory. It will mirror your current working directory to the container.
+
+    Must be run in an initialized libdragon project. This action is a shortcut to the \`exec\` action under the hood.`,
+  },
+};

package/modules/actions/npm-utils.js

@@ -0,0 +1,122 @@
+const path = require('path');
+const fsClassic = require('fs');
+
+const _ = require('lodash');
+
+const { dockerHostUserParams } = require('./docker-utils');
+
+const { CONTAINER_TARGET_PATH } = require('../constants');
+const {
+  fileExists,
+  toPosixPath,
+  spawnProcess,
+  dockerExec,
+  ValidationError,
+} = require('../helpers');
+
+async function findNPMRoot() {
+  try {
+    const root = path.resolve((await runNPM(['root'])).trim(), '..');
+    // Only report if package.json really exists. npm fallbacks to cwd
+    if (await fileExists(path.join(root, 'package.json'))) {
+      return root;
+    }
+  } catch {
+    // User does not have and does not care about NPM if it didn't work
+    return undefined;
+  }
+}
+
+// Install other NPM dependencies if this is an NPM project
+const installNPMDependencies = async (libdragonInfo) => {
+  const npmRoot = await findNPMRoot();
+  if (npmRoot) {
+    const packageJsonPath = path.join(npmRoot, 'package.json');
+
+    const { dependencies, devDependencies } = require(packageJsonPath);
+
+    const deps = await Promise.all(
+      Object.keys({
+        ...dependencies,
+        ...devDependencies,
+      })
+        .filter((dep) => dep !== 'libdragon')
+        .map(async (dep) => {
+          const npmPath = await runNPM(['ls', dep, '--parseable=true']);
+          return {
+            name: dep,
+            paths: _.uniq(npmPath.split('\n').filter((f) => f)),
+          };
+        })
+    );
+
+    await Promise.all(
+      deps.map(({ name, paths }) => {
+        return new Promise((resolve, reject) => {
+          fsClassic.access(
+            path.join(paths[0], 'Makefile'),
+            fsClassic.F_OK,
+            async (e) => {
+              if (e) {
+                // File does not exist - skip
+                resolve();
+                return;
+              }
+
+              if (paths.length > 1) {
+                reject(
+                  new ValidationError(
+                    `Using same dependency with different versions is not supported! ${name}`
+                  )
+                );
+                return;
+              }
+
+              try {
+                const relativePath = toPosixPath(
+                  path.relative(libdragonInfo.root, paths[0])
+                );
+                const containerPath = path.posix.join(
+                  CONTAINER_TARGET_PATH,
+                  relativePath
+                );
+                const makePath = path.posix.join(containerPath, 'Makefile');
+
+                await dockerExec(
+                  libdragonInfo,
+                  [...dockerHostUserParams(libdragonInfo)],
+                  [
+                    '/bin/bash',
+                    '-c',
+                    '[ -f ' +
+                      makePath +
+                      ' ] && make -C ' +
+                      containerPath +
+                      ' && make -C ' +
+                      containerPath +
+                      ' install',
+                  ]
+                );
+
+                resolve();
+              } catch (e) {
+                reject(e);
+              }
+            }
+          );
+        });
+      })
+    );
+  }
+};
+
+function runNPM(params) {
+  return spawnProcess(
+    /^win/.test(process.platform) ? 'npm.cmd' : 'npm',
+    params
+  );
+}
+module.exports = {
+  installNPMDependencies,
+  findNPMRoot,
+};

package/modules/actions/start.js

@@ -2,7 +2,6 @@ const chalk = require('chalk');
 
 const { CONTAINER_TARGET_PATH } = require('../constants');
 const { spawnProcess, log, dockerExec } = require('../helpers');
-const { setProjectInfoToSave } = require('../project-info');
 
 const {
   checkContainerAndClean,
@@ -76,8 +75,6 @@ const initContainer = async (libdragonInfo) => {
       chalk.green(`Successfully initialized docker container: ${name.trim()}`)
     );
 
-  // Schedule an update to write image name
-  setProjectInfoToSave(libdragonInfo);
   return newId;
 };
 
@@ -108,7 +105,18 @@ const start = async (libdragonInfo, skipProjectCheck) => {
 
 module.exports = {
   name: 'start',
-  fn: async (libdragonInfo) => log(await start(libdragonInfo)),
+  fn: async (libdragonInfo) => {
+    const containerId = await start(libdragonInfo);
+    log(containerId);
+    return { ...libdragonInfo, containerId };
+  },
   start,
   showStatus: false, // This will only print out the id
+  usage: {
+    name: 'start',
+    summary: 'Start the container for current project.',
+    description: `Start the container assigned to the current libdragon project. Will first attempt to start an existing container if found, followed by a new container run and installation similar to the \`install\` action. Will always print out the container id on success.
+
+      Must be run in an initialized libdragon project.`,
+  },
 };

package/modules/actions/stop.js

@@ -12,10 +12,18 @@ const stop = async (libdragonInfo) => {
   }
 
   await spawnProcess('docker', ['container', 'stop', running]);
+  return libdragonInfo;
 };
 
 module.exports = {
   name: 'stop',
   fn: stop,
   showStatus: false, // This will only print out the id
+  usage: {
+    name: 'stop',
+    summary: 'Stop the container for current project.',
+    description: `Stop the container assigned to the current libdragon project.
+
+      Must be run in an initialized libdragon project.`,
+  },
 };

package/modules/actions/update.js

@@ -1,5 +1,3 @@
-const path = require('path');
-
 const { log } = require('../helpers');
 const { LIBDRAGON_GIT, LIBDRAGON_BRANCH } = require('../constants');
 const { runGitMaybeHost, mustHaveProject } = require('./utils');
@@ -27,7 +25,7 @@ const update = async (libdragonInfo) => {
       'subtree',
       'pull',
       '--prefix',
-      path.relative(libdragonInfo.root, libdragonInfo.vendorDirectory),
+      libdragonInfo.vendorDirectory,
       LIBDRAGON_GIT,
       LIBDRAGON_BRANCH,
       '--squash',
@@ -36,11 +34,19 @@ const update = async (libdragonInfo) => {
 
   // The second parameter forces it to skip the image update step as we already
   // do that above.
-  await install(newInfo, true);
+  return await install(newInfo, true);
 };
 
 module.exports = {
   name: 'update',
   fn: update,
   showStatus: true,
+  usage: {
+    name: 'update',
+    summary: 'Update libdragon and do an install.',
+    description: `Will update the docker image and if you are using auto-vendoring (see \`--strategy\`), will also update the submodule/subtree from the remote branch (\`trunk\`) with a merge/squash strategy and then perform a \`libdragon install\`. You can use the \`install\` action to only update all libdragon related artifacts in the container.
+
+      Must be run in an initialized libdragon project.`,
+    group: ['docker'],
+  },
 };

package/modules/actions/utils.js

@@ -1,9 +1,6 @@
 const path = require('path');
-const fsClassic = require('fs');
 const fs = require('fs/promises');
 
-const _ = require('lodash');
-
 const {
   CONTAINER_TARGET_PATH,
   CACHED_CONTAINER_FILE,
@@ -12,7 +9,6 @@ const {
 const {
   fileExists,
   log,
-  toPosixPath,
   spawnProcess,
   dockerExec,
   dirExists,
@@ -20,30 +16,16 @@ const {
   CommandError,
   ValidationError,
   ParameterError,
+  toNativePath,
 } = require('../helpers');
 
-function dockerHostUserParams(libdragonInfo) {
-  const { uid, gid } = libdragonInfo.userInfo;
-  return ['-u', `${uid >= 0 ? uid : ''}:${gid >= 0 ? gid : ''}`];
-}
-
-async function findNPMRoot() {
-  try {
-    const root = path.resolve((await runNPM(['root'])).trim(), '..');
-    // Only report if package.json really exists. npm fallbacks to cwd
-    if (await fileExists(path.join(root, 'package.json'))) {
-      return root;
-    }
-  } catch {
-    // User does not have and does not care about NPM if it didn't work
-    return undefined;
-  }
-}
+const { dockerHostUserParams } = require('./docker-utils');
+const { installNPMDependencies } = require('./npm-utils');
 
 const installDependencies = async (libdragonInfo) => {
   const buildScriptPath = path.join(
     libdragonInfo.root,
-    libdragonInfo.vendorDirectory,
+    toNativePath(libdragonInfo.vendorDirectory),
     'build.sh'
   );
   if (!(await fileExists(buildScriptPath))) {
@@ -58,96 +40,13 @@ const installDependencies = async (libdragonInfo) => {
     libdragonInfo,
     [
       '--workdir',
-      CONTAINER_TARGET_PATH +
-        '/' +
-        toPosixPath(
-          path.relative(libdragonInfo.root, libdragonInfo.vendorDirectory)
-        ),
+      CONTAINER_TARGET_PATH + '/' + libdragonInfo.vendorDirectory,
       ...dockerHostUserParams(libdragonInfo),
     ],
     ['/bin/bash', './build.sh']
   );
 
-  // Install other NPM dependencies if this is an NPM project
-  const npmRoot = await findNPMRoot();
-  if (npmRoot) {
-    const packageJsonPath = path.join(npmRoot, 'package.json');
-
-    const { dependencies, devDependencies } = require(packageJsonPath);
-
-    const deps = await Promise.all(
-      Object.keys({
-        ...dependencies,
-        ...devDependencies,
-      })
-        .filter((dep) => dep !== 'libdragon')
-        .map(async (dep) => {
-          const npmPath = await runNPM(['ls', dep, '--parseable=true']);
-          return {
-            name: dep,
-            paths: _.uniq(npmPath.split('\n').filter((f) => f)),
-          };
-        })
-    );
-
-    await Promise.all(
-      deps.map(({ name, paths }) => {
-        return new Promise((resolve, reject) => {
-          fsClassic.access(
-            path.join(paths[0], 'Makefile'),
-            fsClassic.F_OK,
-            async (e) => {
-              if (e) {
-                // File does not exist - skip
-                resolve();
-                return;
-              }
-
-              if (paths.length > 1) {
-                reject(
-                  new ValidationError(
-                    `Using same dependency with different versions is not supported! ${name}`
-                  )
-                );
-                return;
-              }
-
-              try {
-                const relativePath = toPosixPath(
-                  path.relative(libdragonInfo.root, paths[0])
-                );
-                const containerPath = path.posix.join(
-                  CONTAINER_TARGET_PATH,
-                  relativePath
-                );
-                const makePath = path.posix.join(containerPath, 'Makefile');
-
-                await dockerExec(
-                  libdragonInfo,
-                  [...dockerHostUserParams(libdragonInfo)],
-                  [
-                    '/bin/bash',
-                    '-c',
-                    '[ -f ' +
-                      makePath +
-                      ' ] && make -C ' +
-                      containerPath +
-                      ' && make -C ' +
-                      containerPath +
-                      ' install',
-                  ]
-                );
-
-                resolve();
-              } catch (e) {
-                reject(e);
-              }
-            }
-          );
-        });
-      })
-    );
-  }
+  await installNPMDependencies(libdragonInfo);
 };
 
 /**
@@ -249,13 +148,6 @@ async function runGitMaybeHost(libdragonInfo, params, interactive = 'full') {
   }
 }
 
-function runNPM(params) {
-  return spawnProcess(
-    /^win/.test(process.platform) ? 'npm.cmd' : 'npm',
-    params
-  );
-}
-
 async function checkContainerAndClean(libdragonInfo) {
   const id =
     libdragonInfo.containerId &&
@@ -319,9 +211,7 @@ module.exports = {
   destroyContainer,
   checkContainerRunning,
   checkContainerAndClean,
-  dockerHostUserParams,
   tryCacheContainerId,
   runGitMaybeHost,
-  findNPMRoot,
   mustHaveProject,
 };

package/modules/actions/version.js

@@ -0,0 +1,17 @@
+const { version } = require('../../package.json');
+const { log } = require('../helpers');
+
+const printVersion = async () => {
+  log(`libdragon-cli v${version}`);
+};
+
+module.exports = {
+  name: 'version',
+  fn: printVersion,
+  showStatus: false,
+  usage: {
+    name: 'version',
+    summary: 'Display cli version.',
+    description: `Displays currently running cli version.`,
+  },
+};

package/modules/helpers.js

@@ -209,7 +209,11 @@ async function copyDirContents(src, dst) {
 }
 
 function toPosixPath(p) {
-  return p.replace(new RegExp('\\' + path.sep), path.posix.sep);
+  return p.replace(new RegExp('\\' + path.sep, 'g'), path.posix.sep);
+}
+
+function toNativePath(p) {
+  return p.replace(new RegExp('\\' + path.posix.sep, 'g'), path.sep);
 }
 
 function assert(condition, error) {
@@ -236,6 +240,7 @@ function log(text, verboseOnly = false) {
 module.exports = {
   spawnProcess,
   toPosixPath,
+  toNativePath,
   log,
   dockerExec,
   assert,

package/modules/project-info.js

@@ -4,11 +4,12 @@ const fs = require('fs/promises');
 
 const {
   checkContainerAndClean,
-  findNPMRoot,
   runGitMaybeHost,
   tryCacheContainerId,
 } = require('./actions/utils');
 
+const { findNPMRoot } = require('./actions/npm-utils');
+
 const {
   LIBDRAGON_PROJECT_MANIFEST,
   CONFIG_FILE,
@@ -20,7 +21,13 @@ const {
   CONTAINER_TARGET_PATH,
 } = require('./constants');
 
-const { fileExists, log, spawnProcess, toPosixPath } = require('./helpers');
+const {
+  fileExists,
+  log,
+  spawnProcess,
+  toPosixPath,
+  assert,
+} = require('./helpers');
 
 async function findContainerId(libdragonInfo) {
   const idFile = path.join(libdragonInfo.root, '.git', CACHED_CONTAINER_FILE);
@@ -96,7 +103,7 @@ async function readProjectInfo() {
     // Set the defaults immediately, these should be present at all times even
     // if we are migrating from the old config because they did not exist before
     imageName: DOCKER_HUB_IMAGE,
-    vendorDirectory: path.join('.', LIBDRAGON_SUBMODULE),
+    vendorDirectory: toPosixPath(path.join('.', LIBDRAGON_SUBMODULE)),
     vendorStrategy: DEFAULT_STRATEGY,
   };
 
@@ -158,30 +165,16 @@ async function readProjectInfo() {
   log(`Active vendor directory: ${info.vendorDirectory}`, true);
   log(`Active vendor strategy: ${info.vendorStrategy}`, true);
 
-  // Cache the latest image name
-  setProjectInfoToSave(info);
   return info;
 }
 
-let projectInfoToWrite = {};
 /**
- * Updates project info to be written. The provided keys are overwritten without
- * changing the existing values. When the process exists successfully these will
- * get written to the configuration file. Echoes back the given info.
  * @param info This is only the base info without action properties like showStatus
  * fn and command line options
  */
-function setProjectInfoToSave(info) {
-  projectInfoToWrite = { ...projectInfoToWrite, ...info };
-  return info;
-}
-
-/**
- * @param info This is only the base info without action properties like showStatus
- * fn and command line options
- */
-async function writeProjectInfo(info = projectInfoToWrite) {
+async function writeProjectInfo(info) {
   // Do not log anything here as it may litter the output being always run on exit
+  if (!info) return;
 
   const projectPath = path.join(info.root, LIBDRAGON_PROJECT_MANIFEST);
 
@@ -195,13 +188,17 @@ async function writeProjectInfo(info = projectInfoToWrite) {
     await fs.mkdir(projectPath);
   }
 
+  assert(
+    toPosixPath(info.vendorDirectory) === info.vendorDirectory,
+    new Error('vendorDirectory should always be in posix format')
+  );
+
   await fs.writeFile(
     path.join(projectPath, CONFIG_FILE),
     JSON.stringify(
       {
         imageName: info.imageName,
-        // Always save this in posix format
-        vendorDirectory: toPosixPath(info.vendorDirectory),
+        vendorDirectory: info.vendorDirectory,
         vendorStrategy: info.vendorStrategy,
       },
       null,
@@ -211,4 +208,4 @@ async function writeProjectInfo(info = projectInfoToWrite) {
   log(`Configuration file updated`, true);
 }
 
-module.exports = { readProjectInfo, writeProjectInfo, setProjectInfoToSave };
+module.exports = { readProjectInfo, writeProjectInfo };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libdragon",
-  "version": "10.4.2",
+  "version": "10.5.0",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {

package/skeleton/Makefile

@@ -3,16 +3,17 @@ SOURCE_DIR=src
 BUILD_DIR=build
 include $(N64_INST)/include/n64.mk
 
-src=main.c
-
 all: hello.z64
+.PHONY: all
+
+OBJS = $(BUILD_DIR)/main.o
 
 hello.z64: N64_ROM_TITLE="Hello World"
-$(BUILD_DIR)/hello.elf: $(src:%.c=$(BUILD_DIR)/%.o)
 
-clean:
-	rm -f $(BUILD_DIR)/* hello.z64
+$(BUILD_DIR)/hello.elf: $(OBJS)
 
--include $(wildcard $(BUILD_DIR)/*.d)
+clean:
+	rm -f $(BUILD_DIR) *.z64
+.PHONY: clean
 
-.PHONY: all clean
+-include $(wildcard $(BUILD_DIR)/*.d)