docs: update docs (#1004)

nwutils · Dec 26, 2023 · 0aca6e8 · 0aca6e8
1 parent 0e8fc10
commit 0aca6e8
Show file tree

Hide file tree

Showing 7 changed files with 196 additions and 82 deletions.
diff --git a/README.md b/README.md
@@ -15,78 +15,91 @@ For version 3, please go to the [corresponding branch](https://github.com/nwutil
 - Downloading from mirrors
 - Node Native Addon support
 
-Check out the [documentation](https://nwutils.io/nw-builder/) if you wish to give `nw-builder` a try.
-
-> Please note that the documentation assumes you know [how to write NW.js applications](https://nwjs.readthedocs.io/en/latest/For%20Users/Getting%20Started/).
-
 ## Installation
 
 With npm:
 
 ```shell
-npm install nw-builder -D
+npm i -D nw-builder
 ```
 
 With yarn:
 
 ```shell
-yarn add nw-builder -D
+yarn add -D nw-builder
 ```
 
 With pnpm:
 
 ```shell
-pnpm add nw-builder -D
+pnpm add -D nw-builder
 ```
 
 ## Usage
 
-Here is two way to use nw-build to build your nwjs applications
+You can use this package via CLI or JavaScript module. To customise your configuration options, please consult the [documentation](https://nwutils.io/nw-builder/).
 
 ### CLI
 
-1. To get nwjs cache
-    ```bash
-    nwbuild --mode=get
-    ```
-2. To run nwjs application
-    ```bash
-    nwbuild --mode=run
-    ```
-3. To build nwjs application
-    ```bash
-    nwbuild --mode=build
-    ```
-
-### JavaScript API
-1. Define an npm script
-    ```json
-    {
-      "scripts": {
-        "build": "node scripts/build.js"
-      }
-    }
-    ```
-2. Create a build script
-    ```javascript
-    // scripts/build.js
-    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: { ... },
-    });
-    ```
-3. Run the script
-    ```bash
-    npm run build
-    ```
+Download NW.js binary
+
+```shell
+nwbuild --mode=get
+```
+
+Run NW.js application
+
+```shell
+nwbuild --mode=run
+```
+
+Build NW.js application
+
+```shell
+nwbuild --mode=get
+```
+
+### Module
+
+ESM import
+
+```javascript
+import nwbuild from "nw-builder";
+```
+
+CJS import
+
+```javascript
+import nwbuild from "nw-builder";
+
+let nwbuild = undefined;
+
+nwbuild = await import("nw-builder").default;
+```
+
+Download NW.js binary
+
+```javascript
+nwbuild({
+  mode: "get",
+});
+```
+
+Run NW.js application
+
+```javascript
+nwbuild({
+  mode: "run",
+});
+```
+
+Build NW.js application
+
+```javascript
+nwbuild({
+  mode: "build",
+});
+```
 
 ## Alternatives
 

diff --git a/docs/bld.js.html b/docs/bld.js.html
@@ -523,7 +523,7 @@ <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.htm
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Mon Dec 18 2023 10:37:54 GMT-0500 (Eastern Standard Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Tue Dec 26 2023 16:38:03 GMT+0530 (India Standard Time)
 </footer>
 
 <script> prettyPrint(); </script>

diff --git a/docs/get.js.html b/docs/get.js.html
@@ -41,20 +41,20 @@ <h1 class="page-title">Source: get.js</h1>
 
 /**
  * @typedef {object} GetOptions
- * @property {string | "latest" | "stable" | "lts"} [options.version = "latest"]                  Runtime version
- * @property {"normal" | "sdk"}                     [options.flavor = "normal"]                   Build flavor
- * @property {"linux" | "osx" | "win"}              [options.platform]                            Target platform
- * @property {"ia32" | "x64" | "arm64"}             [options.arch]                                Target arch
- * @property {string}                               [options.downloadUrl = "https://dl.nwjs.io"]  Download server
- * @property {string}                               [options.cacheDir = "./cache"]                Cache directory
- * @property {boolean}                              [options.cache = true]                        If false, remove cache and redownload.
- * @property {boolean}                              [options.ffmpeg = false]                      If true, ffmpeg is not downloaded.
- * @property {false | "gyp"}                        [options.nativeAddon = false]                 Rebuild native modules
+ * @property {string | "latest" | "stable" | "lts"} [version = "latest"]                  Runtime version
+ * @property {"normal" | "sdk"}                     [flavor = "normal"]                   Build flavor
+ * @property {"linux" | "osx" | "win"}              [platform]                            Target platform
+ * @property {"ia32" | "x64" | "arm64"}             [arch]                                Target arch
+ * @property {string}                               [downloadUrl = "https://dl.nwjs.io"]  Download server
+ * @property {string}                               [cacheDir = "./cache"]                Cache directory
+ * @property {boolean}                              [cache = true]                        If false, remove cache and redownload.
+ * @property {boolean}                              [ffmpeg = false]                      If true, ffmpeg is not downloaded.
+ * @property {false | "gyp"}                        [nativeAddon = false]                 Rebuild native modules
  */
 
 /**
  * Get binaries.
- * 
+ *
  * @async
  * @function
  * @param  {GetOptions}    options                  Get mode options
@@ -65,11 +65,11 @@ <h1 class="page-title">Source: get.js</h1>
  * nwbuild({
  *   mode: "get",
  * });
- * 
+ *
  * // Use with nw module
  * nwbuild({
  *   mode: "get",
- *   cacheDir: "./node_modules/nw" 
+ *   cacheDir: "./node_modules/nw"
  * });
  *
  * @example
@@ -112,6 +112,9 @@ <h1 class="page-title">Source: get.js</h1>
  * });
  */
 async function get(options) {
+  if (fs.existsSync(options.cacheDir) === false) {
+    await fsm.mkdir(options.cacheDir, { recursive: true });
+  }
   await getNwjs(options);
   if (options.ffmpeg === true) {
     await getFfmpeg(options);
@@ -150,8 +153,14 @@ <h1 class="page-title">Source: get.js</h1>
         C: options.cacheDir
       });
     } else {
-      fs.createReadStream(out)
-        .pipe(unzipper.Extract({ path: options.cacheDir }));
+      await new Promise((res) => {
+        fs.createReadStream(out)
+          .pipe(unzipper.Extract({ path: options.cacheDir }))
+          .on("finish", res);
+      });
+      if (options.platform === "osx") {
+        await createSymlinks(options);
+      }
     }
     return;
   }
@@ -221,8 +230,15 @@ <h1 class="page-title">Source: get.js</h1>
       C: options.cacheDir
     });
   } else {
-    fs.createReadStream(out)
-      .pipe(unzipper.Extract({ path: options.cacheDir }));
+    await new Promise((res) => {
+      fs.createReadStream(out)
+        .pipe(unzipper.Extract({ path: options.cacheDir }))
+        .on("finish", res);
+    });
+    if (options.platform === "osx") {
+      await createSymlinks(options);
+    }
+
   }
 }
 
@@ -374,6 +390,22 @@ <h1 class="page-title">Source: get.js</h1>
   );
 }
 
+const createSymlinks = async (options) => {
+  const frameworksPath = path.join(process.cwd(), options.cacheDir, `nwjs${options.flavor === "sdk" ? "-sdk" : ""}-v${options.version}-${options.platform}-${options.arch}`, "nwjs.app", "Contents", "Frameworks", "nwjs Framework.framework");
+  const symlinks = [
+    path.join(frameworksPath, "Helpers"),
+    path.join(frameworksPath, "Libraries"),
+    path.join(frameworksPath, "nwjs Framework"),
+    path.join(frameworksPath, "Resources"),
+    path.join(frameworksPath, "Versions", "Current"),
+  ];
+  for await (const symlink of symlinks) {
+    const link = String(await fsm.readFile(symlink));
+    await fsm.rm(symlink);
+    await fsm.symlink(link, symlink);
+  }
+};
+
 export default get;
 </code></pre>
         </article>
@@ -391,7 +423,7 @@ <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.htm
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Mon Dec 18 2023 10:37:54 GMT-0500 (Eastern Standard Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Tue Dec 26 2023 16:38:03 GMT+0530 (India Standard Time)
 </footer>
 
 <script> prettyPrint(); </script>

diff --git a/docs/global.html b/docs/global.html
@@ -455,7 +455,7 @@ <h5>Examples</h5>
 // Use with nw module
 nwbuild({
   mode: "get",
-  cacheDir: "./node_modules/nw" 
+  cacheDir: "./node_modules/nw"
 });</code></pre>
 
     <pre class="prettyprint"><code>// Unofficial macOS builds (upto v0.75.0)
@@ -1340,7 +1340,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.version</code></td>
+                <td class="name"><code>version</code></td>
 
 
             <td class="type">
@@ -1386,7 +1386,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.flavor</code></td>
+                <td class="name"><code>flavor</code></td>
 
 
             <td class="type">
@@ -1426,7 +1426,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.platform</code></td>
+                <td class="name"><code>platform</code></td>
 
 
             <td class="type">
@@ -1467,7 +1467,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.arch</code></td>
+                <td class="name"><code>arch</code></td>
 
 
             <td class="type">
@@ -1508,7 +1508,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.downloadUrl</code></td>
+                <td class="name"><code>downloadUrl</code></td>
 
 
             <td class="type">
@@ -1545,7 +1545,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.cacheDir</code></td>
+                <td class="name"><code>cacheDir</code></td>
 
 
             <td class="type">
@@ -1582,7 +1582,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.cache</code></td>
+                <td class="name"><code>cache</code></td>
 
 
             <td class="type">
@@ -1619,7 +1619,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.ffmpeg</code></td>
+                <td class="name"><code>ffmpeg</code></td>
 
 
             <td class="type">
@@ -1656,7 +1656,7 @@ <h5 class="subsection-title">Properties:</h5>
 
         <tr>
 
-                <td class="name"><code>options.nativeAddon</code></td>
+                <td class="name"><code>nativeAddon</code></td>
 
 
             <td class="type">
@@ -3571,7 +3571,7 @@ <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.htm
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Mon Dec 18 2023 10:37:54 GMT-0500 (Eastern Standard Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Tue Dec 26 2023 16:38:03 GMT+0530 (India Standard Time)
 </footer>
 
 <script> prettyPrint(); </script>