libdragon 10.0.0 → 10.3.1

package/modules/helpers.js

@@ -9,6 +9,7 @@ const {
   LIBDRAGON_PROJECT_MANIFEST,
   IMAGE_FILE,
   DOCKER_HUB_IMAGE,
+  CONTAINER_TARGET_PATH,
 } = require('./constants');
 
 const globals = {
@@ -16,16 +17,20 @@ const globals = {
 };
 
 class CommandError extends Error {
-  constructor(message, { code, out, showOutput }) {
+  constructor(message, { code, out, userCommand }) {
     super(message);
     this.code = code;
     this.out = out;
-    this.showOutput = showOutput;
+    this.userCommand = userCommand;
   }
 }
 
-// A simple Promise wrapper for child_process.spawn
-function spawnProcess(cmd, params = [], showOutput) {
+// A simple Promise wrapper for child_process.spawn. If interactive is true,
+// stdout becomes a tty when available and we cannot read the stdout from the
+// command anymore. If interactive is "full", the error stream is also piped to
+// the main process as TTY, so it is not readable anymore as well. For the
+// commands using stderr as TTY it should be set to "full"
+function spawnProcess(cmd, params = [], userCommand, interactive = false) {
   return new Promise((resolve, reject) => {
     let stdout = [];
     let stderr = [];
@@ -34,21 +39,41 @@ function spawnProcess(cmd, params = [], showOutput) {
       log(chalk.grey(`Spawning: ${cmd} ${params.join(' ')}`), true);
     }
 
-    const command = spawn(cmd, params);
-
-    command.stdout.on('data', function (data) {
-      if (showOutput || globals.verbose) {
-        process.stdout.write(data);
-      }
-      stdout.push(Buffer.from(data));
+    const isTTY =
+      process.stdin.isTTY && process.stdout.isTTY && process.stderr.isTTY;
+    const enableTTY = isTTY && !!interactive;
+    const enableErrorTTY = isTTY && interactive === 'full';
+
+    const command = spawn(cmd, params, {
+      // We should redirect streams together for the TTY to work
+      // properly if they are all used as TTY
+      stdio: [
+        enableTTY ? 'inherit' : 'pipe',
+        enableTTY ? 'inherit' : 'pipe',
+        enableErrorTTY ? 'inherit' : 'pipe',
+      ],
     });
 
-    command.stderr.on('data', function (data) {
-      if (showOutput || globals.verbose) {
-        process.stderr.write(data);
-      }
-      stderr.push(Buffer.from(data));
-    });
+    if (!enableTTY && (globals.verbose || userCommand)) {
+      command.stdout.pipe(process.stdout);
+    }
+
+    if (!enableErrorTTY && (globals.verbose || userCommand)) {
+      command.stderr.pipe(process.stderr);
+    }
+
+    // We shouldn't need to collect the data if it is a user command.
+    if (!enableTTY && !userCommand) {
+      command.stdout.on('data', function (data) {
+        stdout.push(Buffer.from(data));
+      });
+    }
+
+    if (!enableErrorTTY) {
+      command.stderr.on('data', function (data) {
+        stderr.push(Buffer.from(data));
+      });
+    }
 
     const errorHandler = (err) => {
       command.off('close', closeHandler);
@@ -65,7 +90,7 @@ function spawnProcess(cmd, params = [], showOutput) {
           {
             code,
             out: Buffer.concat(stderr).toString(),
-            showOutput,
+            userCommand,
           }
         );
         reject(err);
@@ -77,29 +102,49 @@ function spawnProcess(cmd, params = [], showOutput) {
   });
 }
 
-function dockerExec(libdragonInfo, dockerParams, cmdWithParams, showOutput) {
+function dockerExec(
+  libdragonInfo,
+  dockerParams,
+  cmdWithParams,
+  userCommand,
+  interactive
+) {
   // TODO: assert for invalid args
   const haveDockerParams =
     Array.isArray(dockerParams) && Array.isArray(cmdWithParams);
+  const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+  // interactive and TTY?
+  const additionalParams =
+    isTTY && (haveDockerParams ? interactive : userCommand) ? ['-it'] : [];
   return spawnProcess(
     'docker',
     [
       'exec',
-      ...(haveDockerParams ? dockerParams : []),
+      ...(haveDockerParams
+        ? [...dockerParams, ...additionalParams]
+        : additionalParams),
       libdragonInfo.containerId,
       ...(haveDockerParams ? cmdWithParams : dockerParams),
     ],
-    haveDockerParams ? showOutput : cmdWithParams
+    haveDockerParams ? userCommand : cmdWithParams,
+    haveDockerParams ? interactive : userCommand
   );
 }
 
 /**
  * Invokes host git with provided params. If host does not have git, falls back
- * to the docker git, with the user set to the user running libdragon.
+ * to the docker git, with the nix user set to the user running libdragon.
  */
-async function runGitMaybeHost(libdragonInfo, params, showOutput) {
+async function runGitMaybeHost(libdragonInfo, params, interactive = 'full') {
   try {
-    return await spawnProcess('git', params, showOutput);
+    return await spawnProcess(
+      'git',
+      params,
+      false,
+      // Windows git is breaking the TTY somehow - disable interactive for now
+      // We are not able to display progress for the initial clone b/c of this
+      /^win/.test(process.platform) ? false : interactive
+    );
   } catch (e) {
     if (!(e instanceof CommandError)) {
       return await dockerExec(
@@ -107,7 +152,8 @@ async function runGitMaybeHost(libdragonInfo, params, showOutput) {
         // Use the host user when initializing git as we will need access
         [...dockerHostUserParams(libdragonInfo)],
         ['git', ...params],
-        showOutput
+        false,
+        interactive
       );
     }
     throw e;
@@ -148,16 +194,16 @@ async function findNPMRoot() {
   }
 }
 
-function dockerRelativeWorkdirParams(libdragonInfo) {
-  return [
-    '--workdir',
-    '/libdragon/' +
-      toPosixPath(path.relative(libdragonInfo.root, process.cwd())),
-  ];
+function dockerRelativeWorkdir(libdragonInfo) {
+  return (
+    CONTAINER_TARGET_PATH +
+    '/' +
+    toPosixPath(path.relative(libdragonInfo.root, process.cwd()))
+  );
 }
 
-function dockerByteSwapParams(libdragonInfo) {
-  return libdragonInfo.options.BYTE_SWAP ? ['-e', 'N64_BYTE_SWAP=true'] : [];
+function dockerRelativeWorkdirParams(libdragonInfo) {
+  return ['--workdir', dockerRelativeWorkdir(libdragonInfo)];
 }
 
 function dockerHostUserParams(libdragonInfo) {
@@ -174,6 +220,40 @@ async function findGitRoot() {
   }
 }
 
+async function findContainerId(libdragonInfo) {
+  const idFile = path.join(libdragonInfo.root, '.git', CACHED_CONTAINER_FILE);
+  if (fs.existsSync(idFile)) {
+    const id = fs.readFileSync(idFile, { encoding: 'utf8' }).trim();
+    log(`Read containerId: ${id}`, true);
+    return id;
+  }
+
+  const candidates = (
+    await spawnProcess('docker', [
+      'container',
+      'ls',
+      '-a',
+      '--format',
+      '{{.}}{{.ID}}',
+      '-f',
+      'volume=' + CONTAINER_TARGET_PATH,
+    ])
+  )
+    .split('\n')
+    .filter((s) => s.includes(`${libdragonInfo.root} `));
+
+  if (candidates.length > 0) {
+    const str = candidates[0];
+    const shortId = str.slice(-12);
+    const idIndex = str.indexOf(shortId);
+    const longId = str.slice(idIndex, idIndex + 64);
+    if (longId.length === 64) {
+      tryCacheContainerId({ ...libdragonInfo, containerId: longId });
+      return longId;
+    }
+  }
+}
+
 async function checkContainerAndClean(libdragonInfo) {
   const id =
     libdragonInfo.containerId &&
@@ -224,62 +304,59 @@ async function readProjectInfo() {
   if (!info.root) {
     log('Could not find project root, set as cwd.', true);
     info.root = process.cwd();
-    return info;
   }
 
   log(`Project root: ${info.root}`, true);
 
-  const idFile = path.join(info.root, '.git', CACHED_CONTAINER_FILE);
-  if (fs.existsSync(idFile)) {
-    const id = fs.readFileSync(idFile, { encoding: 'utf8' }).trim();
-    log(`Read containerId: ${id}`, true);
-    info.containerId = id;
-  }
-
   const imageFile = path.join(
     info.root,
     LIBDRAGON_PROJECT_MANIFEST,
     IMAGE_FILE
   );
 
+  // flag has the highest priority followed by the one read from the file
+  // and then if there is any matching container, name is read from it. As last
+  // option fallback to default value.
   if (fs.existsSync(imageFile) && !fs.statSync(imageFile).isDirectory()) {
     info.imageName = fs.readFileSync(imageFile, { encoding: 'utf8' }).trim();
   }
 
-  return info;
-}
-
-async function updateImageName(libdragonInfo) {
-  const manifestPath = path.join(
-    libdragonInfo.root,
-    LIBDRAGON_PROJECT_MANIFEST
-  );
-
-  // flag has the highest priority followed by the one read from the file
-  // and then if there is any matching container, name is read from it. As last
-  // option fallback to default value.
-  let imageName = libdragonInfo.options.DOCKER_IMAGE ?? libdragonInfo.imageName;
+  info.containerId = await findContainerId(info);
+  log(`Active container id: ${info.containerId}`, true);
 
-  if (!imageName) {
-    // If still have the container, read the image name
-    const containerId = await checkContainerAndClean(libdragonInfo);
-    if (containerId) {
-      imageName = await spawnProcess('docker', [
+  // If still have the container, read the image name from it
+  if (!info.imageName && (await checkContainerAndClean(info))) {
+    info.imageName = (
+      await spawnProcess('docker', [
         'container',
         'inspect',
-        containerId,
+        info.containerId,
         '--format',
         '{{.Config.Image}}',
-      ]);
-    }
+      ])
+    ).trim();
+
+    // Cache the image name
+    await updateImageName(info);
   }
 
-  imageName = imageName ?? DOCKER_HUB_IMAGE;
+  info.imageName = info.imageName ?? DOCKER_HUB_IMAGE;
+  log(`Active image name: ${info.imageName}`, true);
+  return info;
+}
 
+async function updateImageName(libdragonInfo) {
+  if (!libdragonInfo.imageName) return;
+  const manifestPath = path.join(
+    libdragonInfo.root,
+    LIBDRAGON_PROJECT_MANIFEST
+  );
   await createManifestIfNotExist(libdragonInfo);
-  fs.writeFileSync(path.join(manifestPath, IMAGE_FILE), imageName);
-  log(`Image name updated: ${imageName}`, true);
-  return imageName;
+  fs.writeFileSync(
+    path.join(manifestPath, IMAGE_FILE),
+    libdragonInfo.imageName
+  );
+  log(`Image name updated: ${libdragonInfo.imageName}`, true);
 }
 
 /**
@@ -302,9 +379,17 @@ async function createManifestIfNotExist(libdragonInfo) {
       `Creating libdragon project configuration at \`${libdragonInfo.root}\`.`
     );
     fs.mkdirSync(manifestPath);
-    return true;
   }
-  return false;
+}
+
+function tryCacheContainerId(libdragonInfo) {
+  const gitFolder = path.join(libdragonInfo.root, '.git');
+  if (fs.existsSync(gitFolder) && fs.statSync(gitFolder).isDirectory()) {
+    fs.writeFileSync(
+      path.join(libdragonInfo.root, '.git', CACHED_CONTAINER_FILE),
+      libdragonInfo.containerId
+    );
+  }
 }
 
 function toPosixPath(p) {
@@ -337,9 +422,10 @@ module.exports = {
   log,
   dockerExec,
   dockerRelativeWorkdirParams,
-  dockerByteSwapParams,
   runGitMaybeHost,
   dockerHostUserParams,
+  dockerRelativeWorkdir,
+  tryCacheContainerId,
   CommandError,
   globals,
 };

package/modules/usage.js

@@ -0,0 +1,129 @@
+const chalk = require('chalk');
+const commandLineUsage = require('command-line-usage');
+
+const { log } = require('./helpers');
+
+const printUsage = (_, actionArr) => {
+  const globalOptionDefinitions = [
+    {
+      name: 'verbose',
+      description: 'Be verbose',
+      alias: 'v',
+      group: 'global',
+    },
+  ];
+
+  const optionDefinitions = [
+    {
+      name: 'image',
+      description: 'Provide a custom image.',
+      alias: 'i',
+      typeLabel: '<docker-image>',
+      group: 'docker',
+    },
+  ];
+
+  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.
+
+      A git repository and a submodule at \`./libdragon\` will also be created. Do not remove the \`.libdragon\` folder and commit its contents if you are using git, as it keeps persistent libdragon project information.
+
+      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'],
+    },
+    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 \`libdragon\` at the root of the project. If you are not working on libdragon, 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:
+        'This action will update the submodule from the remote branch (`trunk`) with a merge strategy and then perform a `libdragon install`. 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));
+
+  const sections = [
+    {
+      header: chalk.green('Usage:'),
+      content: 'libdragon [flags] <action>',
+    },
+    ...(actionsToShow?.length
+      ? actionsToShow.flatMap((action) => [
+          {
+            header: chalk.green(`${action} action:`),
+            content: actions[action].description,
+          },
+          actions[action].group
+            ? {
+                header: `accepted flags:`,
+                optionList: optionDefinitions,
+                group: actions[action].group,
+              }
+            : {},
+        ])
+      : [
+          {
+            header: chalk.green('Available Commands:'),
+            content: Object.values(actions).map((action) => ({
+              name: action.name,
+              summary: action.summary,
+            })),
+          },
+        ]),
+    {
+      header: chalk.green('Global flags:'),
+      optionList: globalOptionDefinitions,
+    },
+  ];
+  const usage = commandLineUsage(sections);
+  log(usage);
+};
+
+module.exports = {
+  printUsage,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libdragon",
-  "version": "10.0.0",
+  "version": "10.3.1",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {
@@ -24,7 +24,8 @@
     "url": "git+https://github.com/anacierdem/libdragon-docker.git"
   },
   "files": [
-    "modules/**/*"
+    "modules/**/*",
+    "skeleton/**"
   ],
   "author": "Ali Naci Erdem",
   "license": "MIT",
@@ -34,10 +35,11 @@
   "homepage": "https://github.com/anacierdem/libdragon-docker#readme",
   "dependencies": {
     "chalk": "^4.1.0",
+    "command-line-usage": "^6.1.1",
     "lodash": "^4.17.20"
   },
   "devDependencies": {
-    "ed64": "^2.0.2",
+    "ed64": "^2.0.3",
     "eslint": "^7.32.0",
     "pkg": "^5.3.1",
     "prettier": "^2.4.0"

package/skeleton/Makefile

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

package/skeleton/src/main.c

@@ -0,0 +1,15 @@
+#include <stdio.h>
+
+#include <libdragon.h>
+
+int main(void)
+{
+    console_init();
+
+    debug_init_usblog();
+    console_set_debug(true);
+
+    printf("Hello world!\n");
+
+    while(1) {}
+}