nw-builder 4.4.0 → 4.4.2

package/LICENSE

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Steffen Müller
+Copyright (c) 2021-2023 NW.js Utilities
+Copyright (c) 2014-2021 Steffen Müller
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -9,10 +9,10 @@ For version 3, please go to the [corresponding branch](https://github.com/nwutil
 
 ## Major Features
 
-- Build for Linux, MacOS, and Windows
-- Support downloading [from](https://npm.taobao.org/mirrors/nwjs) [mirrors](https://npmmirror.com/mirrors/nwjs)
-- Integrate [`nwjs-ffmpeg-prebuilt`](https://github.com/nwjs-ffmpeg-prebuilt/nwjs-ffmpeg-prebuilt)
+- Get, run or build applications.
+- Integrate [FFmpeg community builds](https://github.com/nwjs-ffmpeg-prebuilt/nwjs-ffmpeg-prebuilt)
 - Configure executable fields and icons
+- Support downloading from mirrors
 
 Check out the [documentation](https://nwutils.io/nw-builder/) if you wish to give `nw-builder` a try.
 
@@ -22,3 +22,204 @@ Check out the [documentation](https://nwutils.io/nw-builder/) if you wish to giv
 
 - [nw-builder-platforms](https://github.com/naviapps/nw-builder-platforms) - Fork of this repo with platform specific build options
 - [nwjs-builder-phoenix](https://github.com/evshiron/nwjs-builder-phoenix) - Previously the most used build tool, however it is no longer maintained
+
+## Migration Guide (v3 -> v4)
+
+> We are working on making the migration process smoother. If you encounter any issues with the current guide, please open an issue or start a discussion.
+
+### Update `nw-builder`
+
+With npm:
+
+```shell
+npm update nw-builder@latest
+```
+
+With yarn:
+
+```shell
+yarn upgrade nw-builder@latest
+```
+
+With pnpm:
+
+```shell
+pnpm update nw-builder@latest
+```
+
+### Update options
+
+Let's take an example of v3 code and migrate it to v4.
+
+```javascript
+const NwBuilder = require("nw-builder");
+
+const nw = new NwBuilder({
+  files: ["./nwapp/**/*", "./other/**/*.js"],
+  version: "latest",
+  flavor: "normal",
+  platforms: ["win32", "win64", "osx32", "osx64", "linux32", "linux64"],
+  cacheDir: "./cache",
+  buildDir: "./build",
+  buildType: "versioned",
+  forceDownload: true,
+  appName: "nwdemo",
+  appVersion: "0.1.0",
+  argv: "--nw-stderr-logging",
+  macCredits: "./nwapp/credits.html",
+  macIcns: "./nwapp/mac.icns",
+  macPlist: { ... },
+  winVersionString: { ... },
+  winIco: "./nwapp/win.ico",
+  zip: true,
+  macZip: false,
+  mergeZip: false,
+});
+
+nw.build();
+```
+
+Update the import path
+
+```diff
+-const NwBuilder = require("nw-builder");
++const nwbuild = require("nw-builder");
+```
+
+Replace the `NwBuilder` initialization with a function
+
+```diff
+-const nw = new NwBuilder({
++await nwbuild({
+```
+
+The `files` property has been renamed to `srcDir`.
+
+```diff
+-  files: ["./nwapp/**/*", "./other/**/*.js"],
++  srcDir: "./nwapp/**/* ./other/**/*.js",
+```
+
+Add the `mode` option and remove the now redundant `nw.build` function call. The `build` call is made by `nwbuild` internally.
+
+```diff
++  mode: "build",
+
+-nw.build();
+```
+
+The `platforms` option has been removed and replaced with `platform` and `arch`. Notice that one `nwbuild` function call now creates one build for one platform and one arch only.
+
+```diff
+-  platforms: ["win32", "win64", "osx32", "osx64", "linux32", "linux64"],
++  platform: "linux", // "osx" for MacOS "win",  for Windows
++  arch: "x64", // "ia32" for 32 bit or "arm64" for arm based 65 bit architectures
+```
+
+The `buildDir` option has been rename to `outDir`.
+
+```diff
+-  buildDir: "./build",
++  outDir: "./build",
+```
+
+The `buildType` option has been removed.
+
+```diff
+-  buildType: "versioned",
+```
+
+The `forceDownload` option has been changed to `cache`.
+
+```diff
+-  forceDownload: true,
++  cache: false,
+```
+
+The `appName` option has been changed to `app.name`.
+
+```diff
+-  appName: "nwdemo",
++  app: { name: "nwdemo" },
+```
+
+The `appVersion` option has been changed to `app.version`.
+
+```diff
+-  appVersion: "0.1.0",
++  app: { version: "0.1.0" },
+```
+
+The `macCredit` option has been removed.
+
+```diff
+-  macCredits: "./nwapp/credits.html",
+```
+
+The `macIcns` option has been replaced with `icon`.
+
+```diff
+-  macIcns: "./nwapp/mac.icns",
++  icon: "./nwapp/mac.icns",
+```
+
+The `macPlist` option has been replaced by `app.*` options. Consult the [documentation](https://nwutils.io/nw-builder/mode-build.html#osxrc-object) for valid properties.
+
+```diff
+-  macPlist: { ... },
++  app: { ... },
+```
+
+The `winVersionString` option has been replaced with `app`. Consult the [documentation](https://nwutils.io/nw-builder/mode-build.html#winrc-object) for valid properties.
+
+```diff
+-  winVersionString: {
+-    'CompanyName': 'Some Company',
+-    'FileDescription': 'Process Name',
+-    'ProductName': 'Some Product',
+-    'LegalCopyright': 'Copyright 2017',
+-  }
++  app: {
++    company: "Some Company",
++    fileDescription: "Process Name",
++    productName: "Some Product",
++    legalCopyright: "Copyright (c) 2023",
++  }
+```
+
+The `winIco` option has been replaced by `app.icon`.
+
+```diff
+-  winIco: "./nwapp/win.ico",
++  app: { icon: "./nwapp/win.ico" },
+```
+
+The `macZip` option has been removed.
+
+```diff
+-  macZip: false,
+```
+
+The `mergeZip` option has been removed.
+
+```diff
+-  mergeZip: false,
+```
+
+The final code should look like this.
+
+```javascript
+const { nwbuild } = require("nw-builder");
+
+await nwbuild({
+  srcDir: "./nwapp/**/* ./other/**/*.js",
+  mode: "build",
+  version: "latest",
+  flavor: "normal",
+  platform: "linux",
+  arch: "x64",
+  outDir: "./build",
+  cache: false,
+  app: { ... },
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nw-builder",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "description": "Build NW.js desktop applications for MacOS, Windows and Linux.",
   "keywords": [
     "NW.js",
@@ -41,35 +41,37 @@
   },
   "scripts": {
     "ci:fmt": "prettier --check \"./**/*.{css,html,js,json,md,yml}\"",
-    "ci:lnt": "eslint --config=cfg/eslint.config.cjs cfg src test",
+    "ci:lnt": "eslint --config=.github/eslint.config.cjs .github src test",
     "fmt": "prettier --write \"./**/*.{css,html,js,json,md,yml}\"",
-    "lnt": "eslint --config=cfg/eslint.config.cjs --fix cfg src test",
-    "doc:dev": "concurrently --kill-others \"node cfg/fswatch.config.js\" \"vitepress dev doc\"",
-    "doc:bld": "vitepress build doc",
+    "lnt": "eslint --config=.github/eslint.config.cjs --fix src test",
+    "doc:dev": "concurrently --kill-others \"node .github/fswatch.config.js\" \"vitepress dev doc\"",
+    "doc:bld": "node .github/jsdoc.config.cjs && vitepress build doc",
     "test:unit": "node --test test/unit/index.js",
     "test:e2e": "node --test test/e2e/index.js",
-    "test:mod": "cd test/fixture && node demo.js",
-    "test:cli": "cd test/fixture && nwbuild --platform win --arch x64 --outDir out --no-glob app"
+    "demo": "cd test/fixture && node demo.js"
   },
   "devDependencies": {
-    "concurrently": "^8.2.0",
-    "eslint": "^8.45.0",
-    "eslint-config-tjw-jsdoc": "^1.0.3",
+    "concurrently": "^8.2.1",
+    "eslint": "^8.51.0",
+    "eslint-config-tjw-jsdoc": "^1.0.4",
     "gh-pages": "^6.0.0",
     "jsdoc": "^4.0.2",
     "jsdoc-to-markdown": "^8.0.0",
-    "prettier": "^3.0.1",
-    "selenium-webdriver": "^4.10.0",
-    "vitepress": "^1.0.0-beta.5"
+    "prettier": "^3.0.3",
+    "selenium-webdriver": "^4.14.0",
+    "vitepress": "^1.0.0-rc.21"
   },
   "dependencies": {
     "cli-progress": "^3.12.0",
-    "compressing": "^1.9.0",
-    "glob": "^10.3.3",
+    "compressing": "^1.10.0",
+    "glob": "^10.3.10",
     "plist": "^3.1.0",
     "rcedit": "^4.0.0",
-    "winston": "^3.9.0",
+    "winston": "^3.11.0",
     "yargs": "^17.7.2"
   },
-  "packageManager": "npm@9.8.1"
+  "packageManager": "npm@9.8.1",
+  "engines": {
+    "node": "^16.20.1 || ^18.18.2 || >= 20.8.1"
+  }
 }

package/src/build.js

@@ -0,0 +1,318 @@
+import { resolve } from "node:path";
+import { platform as PLATFORM } from "node:process";
+import {
+  cp,
+  copyFile,
+  rename,
+  readFile,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+
+import compressing from "compressing";
+import rcedit from "rcedit";
+import plist from "plist";
+
+import { log } from "./log.js";
+
+/**
+ * References:
+ * https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html
+ *
+ * @typedef  {object}   LinuxRc               Linux configuration options
+ * @property {string}   name                  Name of the application
+ * @property {string}   genericName           Generic name of the application
+ * @property {boolean}  noDisplay             If true the application is not displayed
+ * @property {string}   comment               Tooltip for the entry, for example "View sites on the Internet".
+ * @property {string}   icon                  Icon to display in file manager, menus, etc.
+ * @property {boolean}  hidden                TBD
+ * @property {string[]} onlyShowIn            A list of strings identifying the desktop environments that should (/not) display a given desktop entry
+ * @property {string[]} notShowIn             A list of strings identifying the desktop environments that should (/not) display a given desktop entry
+ * @property {boolean}  dBusActivatable       A boolean value specifying if D-Bus activation is supported for this application
+ * @property {string}   tryExec               Path to an executable file on disk used to determine if the program is actually installed
+ * @property {string}   exec                  Program to execute, possibly with arguments.
+ * @property {string}   path                  If entry is of type Application, the working directory to run the program in.
+ * @property {boolean}  terminal              Whether the program runs in a terminal window.
+ * @property {string[]} actions               Identifiers for application actions.
+ * @property {string[]} mimeType              The MIME type(s) supported by this application.
+ * @property {string[]} categories            Categories in which the entry should be shown in a menu
+ * @property {string[]} implements            A list of interfaces that this application implements.
+ * @property {string[]} keywords              A list of strings which may be used in addition to other metadata to describe this entry.
+ * @property {boolean}  startupNotify         If true, it is KNOWN that the application will send a "remove" message when started with the DESKTOP_STARTUP_ID environment variable set. If false, it is KNOWN that the application does not work with startup notification at all.
+ * @property {string}   startupWMClass        If specified, it is known that the application will map at least one window with the given string as its WM class or WM name hin
+ * @property {boolean}  prefersNonDefaultGPU  If true, the application prefers to be run on a more powerful discrete GPU if available.
+ * @property {string}   singleMainWindow      If true, the application has a single main window, and does not support having an additional one opened.
+ */
+
+/**
+ * References:
+ * https://developer.apple.com/documentation/bundleresources/information_property_list
+ *
+ * @typedef  {object} OsxRc                       OSX resource configuration options
+ * @property {string} name                        The name of the application
+ * @property {string} icon                        The path to the icon file. It should be a .icns file.
+ * @property {string} LSApplicationCategoryType   The category that best describes your app for the App Store.
+ * @property {string} CFBundleIdentifier          A unique identifier for a bundle usually in reverse DNS format.
+ * @property {string} CFBundleName                A user-visible short name for the bundle.
+ * @property {string} CFBundleDisplayName         The user-visible name for the bundle.
+ * @property {string} CFBundleSpokenName          A replacement for the app name in text-to-speech operations.
+ * @property {string} CFBundleVersion             The version of the build that identifies an iteration of the bundle.
+ * @property {string} CFBundleShortVersionString  The release or version number of the bundle.
+ * @property {string} NSHumanReadableCopyright    A human-readable copyright notice for the bundle.
+ */
+
+/**
+ * References:
+ * https://learn.microsoft.com/en-us/windows/win32/msi/version
+ * https://learn.microsoft.com/en-gb/windows/win32/sbscs/application-manifests
+ * https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/deployment/trustinfo-element-clickonce-application?view=vs-2015#requestedexecutionlevel
+ * https://learn.microsoft.com/en-gb/windows/win32/menurc/versioninfo-resource
+ *
+ * @typedef {object} WinRc              Windows configuration options. More info
+ * @property {string} name              The name of the application
+ * @property {string} version           The version of the application
+ * @property {string} comments          Additional information that should be displayed for diagnostic purposes.
+ * @property {string} company           Company that produced the file—for example, Microsoft Corporation or Standard Microsystems Corporation, Inc. This string is required.
+ * @property {string} fileDescription   File description to be presented to users. This string may be displayed in a list box when the user is choosing files to install. For example, Keyboard Driver for AT-Style Keyboards. This string is required.
+ * @property {string} fileVersion       Version number of the file. For example, 3.10 or 5.00.RC2. This string is required.
+ * @property {string} icon              The path to the icon file. It should be a .ico file.
+ * @property {string} internalName      Internal name of the file, if one exists—for example, a module name if the file is a dynamic-link library. If the file has no internal name, this string should be the original filename, without extension. This string is required.
+ * @property {string} legalCopyright    Copyright notices that apply to the file. This should include the full text of all notices, legal symbols, copyright dates, and so on. This string is optional.
+ * @property {string} legalTrademark    Trademarks and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, trademark numbers, and so on. This string is optional.
+ * @property {string} originalFilename  Original name of the file, not including a path. This information enables an application to determine whether a file has been renamed by a user. The format of the name depends on the file system for which the file was created. This string is required.
+ * @property {string} privateBuild      Information about a private version of the file—for example, Built by TESTER1 on \\TESTBED. This string should be present only if VS_FF_PRIVATEBUILD is specified in the fileflags parameter of the root block.
+ * @property {string} productName       Name of the product with which the file is distributed. This string is required.
+ * @property {string} productVersion    Version of the product with which the file is distributed—for example, 3.10 or 5.00.RC2. This string is required.
+ * @property {string} specialBuild      Text that specifies how this version of the file differs from the standard version—for example, Private build for TESTER1 solving mouse problems on M250 and M250E computers. This string should be present only if VS_FF_SPECIALBUILD is specified in the fileflags parameter of the root block.
+ */
+
+/**
+ * Generate NW build artifacts
+ *
+ * Note: File permissions are incorrectly set for Linux or MacOS apps built on Windows platform. For more info: https://www.geeksforgeeks.org/node-js-fs-chmod-method
+ *
+ * Note: To edit Windows executable resources, we use [`rcedit`](https://github.com/electron/node-rcedit). To use rcedit on non-Windows platforms, you will have to install [Wine](https://www.winehq.org/).
+ *
+ * Note: We recursively glob the file patterns given by the user. The first `package.json` parsed is taken to be the NW.js manifest file. If you have multiple manifest files, the first glob pattern should be the path to the NW.js manifest. Choosing a Node manifest at `./package.json` is the most convenient option.
+ *
+ * Note: If you are using the MacOS ARM unofficial builds, you will need to [remove the `com.apple.qurantine` flag](https://github.com/corwin-of-amber/nw.js/releases/tag/nw-v0.75.0):
+ *
+ * `sudo xattr -r -d com.apple.quarantine nwjs.app`
+ *
+ * @example
+ * // Minimal Usage (uses default values)
+ * nwbuild({
+ *   mode: "build",
+ * });
+ *
+ * @param  {string | string[]}       files     Array of NW app files
+ * @param  {string}                  nwDir     Directory to hold NW binaries
+ * @param  {string}                  outDir    Directory to store build artifacts
+ * @param  {"linux" | "osx" | "win"} platform  Platform is the operating system type
+ * @param  {"zip" | boolean}         zip       Specify if the build artifacts are to be zipped
+ * @param  {LinuxRc | OsxRc | WinRc} app       Multi platform configuration options
+ * @return {Promise<undefined>}
+ */
+export async function build(files, nwDir, outDir, platform, zip, app) {
+  log.debug(`Remove any files at ${outDir} directory`);
+  await rm(outDir, { force: true, recursive: true });
+  log.debug(`Copy ${nwDir} files to ${outDir} directory`);
+  await cp(nwDir, outDir, { recursive: true, verbatimSymlinks: true });
+
+  log.debug(`Copy files in srcDir to ${outDir} directory`);
+
+  if (typeof files === "string") {
+    await cp(
+      files,
+      resolve(
+        outDir,
+        platform !== "osx"
+          ? "package.nw"
+          : "nwjs.app/Contents/Resources/app.nw",
+      ),
+      { recursive: true, verbatimSymlinks: true },
+    );
+  } else {
+    for (let file of files) {
+      log.debug(`Copy ${file} file to ${outDir} directory`);
+      await cp(
+        file,
+        resolve(
+          outDir,
+          platform !== "osx"
+            ? "package.nw"
+            : "nwjs.app/Contents/Resources/app.nw",
+          file,
+        ),
+        { recursive: true, verbatimSymlinks: true },
+      );
+    }
+  }
+
+  log.debug(`Starting platform specific config steps for ${platform}`);
+
+  if (platform === "linux") {
+    if (PLATFORM === "win32") {
+      log.warn(
+        "Linux apps built on Windows platform do not preserve all file permissions. See #716",
+      );
+    }
+    let desktopEntryFile = {
+      Type: "Application",
+      Version: "1.5",
+      Name: app.name,
+      GenericName: app.genericName,
+      NoDisplay: app.noDisplay,
+      Comment: app.comment,
+      Icon: app.icon,
+      Hidden: app.hidden,
+      OnlyShowIn: app.onlyShowIn,
+      NotShowIn: app.notShowIn,
+      DBusActivatable: app.dBusActivatable,
+      TryExec: app.tryExec,
+      Exec: app.name,
+      Path: app.path,
+      Terminal: app.terminal,
+      Actions: app.actions,
+      MimeType: app.mimeType,
+      Categories: app.categories,
+      Implements: app.implements,
+      Keywords: app.keywords,
+      StartupNotify: app.startupNotify,
+      StartupWMClass: app.startupWMClass,
+      PrefersNonDefaultGPU: app.prefersNonDefaultGPU,
+      SingleMainWindow: app.singleMainWindow,
+    };
+
+    await rename(`${outDir}/nw`, `${outDir}/${app.name}`);
+
+    let fileContent = `[Desktop Entry]\n`;
+    Object.keys(desktopEntryFile).forEach((key) => {
+      if (desktopEntryFile[key] !== undefined) {
+        fileContent += `${key}=${desktopEntryFile[key]}\n`;
+        log.debug(`Add ${key}=${desktopEntryFile[key]} to Desktop Entry File`);
+      }
+    });
+    let filePath = `${outDir}/${app.name}.desktop`;
+    await writeFile(filePath, fileContent);
+    log.debug("Desktop Entry file generated");
+  } else if (platform === "win") {
+    let versionString = {
+      Comments: app.comments,
+      CompanyName: app.author,
+      FileDescription: app.fileDescription,
+      FileVersion: app.fileVersion,
+      InternalName: app.name,
+      LegalCopyright: app.legalCopyright,
+      LegalTrademarks: app.legalTrademark,
+      OriginalFilename: app.name,
+      PrivateBuild: app.name,
+      ProductName: app.name,
+      ProductVersion: app.version,
+      SpecialBuild: app.name,
+    };
+
+    Object.keys(versionString).forEach((option) => {
+      if (versionString[option] === undefined) {
+        delete versionString[option];
+      }
+    });
+
+    const rcEditOptions = {
+      "file-version": app.version,
+      "product-version": app.version,
+      "version-string": versionString,
+    };
+
+    if (app.icon) {
+      rcEditOptions.icon = app.icon;
+    }
+
+    try {
+      const outDirAppExe = resolve(outDir, `${app.name}.exe`);
+      await rename(resolve(outDir, "nw.exe"), outDirAppExe);
+      await rcedit(outDirAppExe, rcEditOptions);
+    } catch (error) {
+      log.warn(
+        "Renaming EXE failed or unable to modify EXE. If it's the latter, ensure WINE is installed or build your application Windows platform",
+      );
+      log.error(error);
+    }
+  } else if (platform === "osx") {
+    if (PLATFORM === "win32") {
+      log.warn(
+        "MacOS apps built on Windows platform do not preserve all file permissions. See #716",
+      );
+    }
+
+    try {
+      const outApp = resolve(outDir, `${app.name}.app`);
+      await rename(resolve(outDir, "nwjs.app"), outApp);
+      if (app.icon !== undefined) {
+        await copyFile(
+          resolve(app.icon),
+          resolve(outApp, "Contents", "Resources", "app.icns"),
+        );
+      }
+
+      const infoPlistPath = resolve(outApp, "Contents", "Info.plist");
+      const infoPlistJson = plist.parse(await readFile(infoPlistPath, "utf-8"));
+
+      const infoPlistStringsPath = resolve(
+        outApp,
+        "Contents",
+        "Resources",
+        "en.lproj",
+        "InfoPlist.strings",
+      );
+      const infoPlistStringsData = await readFile(
+        infoPlistStringsPath,
+        "utf-8",
+      );
+
+      let infoPlistStringsDataArray = infoPlistStringsData.split("\n");
+
+      infoPlistStringsDataArray.forEach((line, idx, arr) => {
+        if (line.includes("NSHumanReadableCopyright")) {
+          arr[
+            idx
+          ] = `NSHumanReadableCopyright = "${app.NSHumanReadableCopyright}";`;
+        }
+      });
+
+      infoPlistJson.LSApplicationCategoryType = app.LSApplicationCategoryType;
+      infoPlistJson.CFBundleIdentifier = app.CFBundleIdentifier;
+      infoPlistJson.CFBundleName = app.CFBundleName;
+      infoPlistJson.CFBundleDisplayName = app.CFBundleDisplayName;
+      infoPlistJson.CFBundleSpokenName = app.CFBundleSpokenName;
+      infoPlistJson.CFBundleVersion = app.CFBundleVersion;
+      infoPlistJson.CFBundleShortVersionString = app.CFBundleShortVersionString;
+
+      Object.keys(infoPlistJson).forEach((option) => {
+        if (infoPlistJson[option] === undefined) {
+          delete infoPlistJson[option];
+        }
+      });
+
+      await writeFile(infoPlistPath, plist.build(infoPlistJson));
+      await writeFile(
+        infoPlistStringsPath,
+        infoPlistStringsDataArray.toString().replace(/,/g, "\n"),
+      );
+    } catch (error) {
+      log.error(error);
+    }
+  }
+
+  if (zip !== false) {
+    if (zip === true || zip === "zip") {
+      await compressing.zip.compressDir(outDir, `${outDir}.zip`);
+    } else if (zip === "tar") {
+      await compressing.tar.compressDir(outDir, `${outDir}.tar`);
+    } else if (zip === "tgz") {
+      await compressing.tgz.compressDir(outDir, `${outDir}.tgz`);
+    }
+
+    await rm(outDir, { recursive: true, force: true });
+  }
+}