libdragon 10.4.0 → 10.5.0

package/CHANGELOG.md

@@ -1,6 +1,64 @@
 # Change Log
 
-## [10.4.0] - 2022-03-23
+## [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
+
+- Make sure actions depending on an `init` fail in a non-project directory to
+keep the project state consistent. This fixes #51.
+- `update` action now tries to update the toolchain image as well. Previously
+this was not the case contrary to what someone would expect. Considering it won't
+change the behaviour for non-latest images and the toolchain did not have any
+breaking changes for a long time, this is not considered a breaking change either.
+- `start` action was printing stuff other than the container id. It doesn't
+anymore.
+- Stop unnecessarily printing container id and a few messages related to updates.
+- Fix a potential race condition that might cause unexpected failures.
+- Correct some errors' exit codes.
+### Added
+
+- A new exit code (`4`) to represent unexpected conditions.
+
+### Changed
+
+- Deprecated providing the image flag for `install` action by displaying a
+warning and removing it from documentation, without changing behaviour even
+though it is higly unlikely this feature was ever used. It mainly exists for
+historical reasons and it wil be removed in next major release.
+- Update documentation to warn against changing strategy is a one way operation.
+- Update documentation to reflect `update` action changes.
+- Minor refactors.
+- Update submodule for local environment.
+
+## [10.4.1] - 2022-03-23
 
 ### Fixed
 

package/index.js

@@ -8,9 +8,15 @@ const {
   STATUS_OK,
   STATUS_BAD_PARAM,
   STATUS_ERROR,
+  STATUS_VALIDATION_ERROR,
 } = require('./modules/constants');
 const { globals } = require('./modules/globals');
-const { CommandError, ParameterError } = require('./modules/helpers');
+const {
+  CommandError,
+  ParameterError,
+  ValidationError,
+  log,
+} = require('./modules/helpers');
 const { readProjectInfo, writeProjectInfo } = require('./modules/project-info');
 
 let options = {},
@@ -28,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;
@@ -52,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();
@@ -110,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(
@@ -127,6 +148,12 @@ readProjectInfo()
       printUsage(undefined, [currentAction.name]);
       process.exit(STATUS_BAD_PARAM);
     }
+
+    if (e instanceof ValidationError) {
+      console.error(chalk.red(e.message));
+      process.exit(STATUS_VALIDATION_ERROR);
+    }
+
     const userTargetedError = e instanceof CommandError && e.userCommand;
 
     // Show additional information to user if verbose or we did a mistake
@@ -149,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

@@ -3,8 +3,9 @@ const path = require('path');
 const { CONTAINER_TARGET_PATH } = require('../constants');
 const { log, dockerExec, toPosixPath } = require('../helpers');
 
-const { fn: start } = require('./start');
-const { dockerHostUserParams, installDependencies } = require('./utils');
+const { start } = require('./start');
+const { dockerHostUserParams } = require('./docker-utils');
+const { installDependencies, mustHaveProject } = require('./utils');
 
 function dockerRelativeWorkdir(libdragonInfo) {
   return (
@@ -19,6 +20,8 @@ function dockerRelativeWorkdirParams(libdragonInfo) {
 }
 
 const exec = async (libdragonInfo, commandAndParams) => {
+  await mustHaveProject(libdragonInfo);
+
   log(
     `Running ${commandAndParams[0]} at ${dockerRelativeWorkdir(
       libdragonInfo
@@ -66,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 {
@@ -81,6 +84,7 @@ const exec = async (libdragonInfo, commandAndParams) => {
     }
     await startOnceAndCmd();
   }
+  return libdragonInfo;
 };
 
 module.exports = {
@@ -88,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',
@@ -39,75 +39,15 @@ const printUsage = (_, actionArr) => {
 
         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.
 
-        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.
+        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.
 
-        It is also possible to opt-out later on by running \`init\` with \`--strategy manual\`, though you will be responsible for managing the existing submodule/subtree.\n`,
+        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: 'v',
       typeLabel: '<strategy>',
       group: 'vendoring',
     },
   ];
 
-  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.
-
-      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.`,
-    },
-    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.',
-    },
-    name: {
-      name: 'stop',
-      summary: 'Stop the container for current project.',
-      description:
-        'Stop the container assigned to the current libdragon project.',
-    },
-    install: {
-      name: 'install',
-      summary: 'Vendor libdragon as is.',
-      group: ['docker'],
-      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.
-
-        This can be useful to recover from a half-baked container.`,
-    },
-    update: {
-      name: 'update',
-      summary: 'Update libdragon and do an install.',
-      description:
-        'If you are using auto-vendoring (see `--strategy`), this action will update the submodule/subtree from the remote branch (`trunk`) with a merge/squash strategy and then perform a `libdragon install`. This is the same as an `install` when the vendoring strategy is `manual`. You can use the `install` action to only update all libdragon related artifacts in the container.',
-      group: ['docker'],
-    },
-  };
-
   const actionsToShow = actionArr
     ?.filter((action) => Object.keys(actions).includes(action))
     .filter((action) => !['help'].includes(action));
@@ -115,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,
             })),
           },
         ]),
@@ -154,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,43 +1,17 @@
-const { spawnProcess } = require('../helpers');
-const { checkContainerRunning } = require('./utils');
-
-const { fn: exec } = require('./exec');
-
-const stop = async (libdragonInfo) => {
-  const running =
-    libdragonInfo.containerId &&
-    (await checkContainerRunning(libdragonInfo.containerId));
-  if (!running) {
-    return;
-  }
-
-  await spawnProcess('docker', ['container', 'stop', running]);
-};
-
-const make = async (libdragonInfo, params) => {
-  await exec(libdragonInfo, ['make', ...params]);
-};
-
-// TODO: separate into files
 module.exports = {
   start: require('./start'),
-  stop: {
-    name: 'stop',
-    fn: stop,
-    showStatus: false, // This will only print out the id
-  },
+  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'),
 };