From 3c66e810c061f441bdaab0449ae09c720eca3d48 Mon Sep 17 00:00:00 2001 From: Felix Rieseberg Date: Mon, 19 Feb 2018 17:50:38 -0600 Subject: [PATCH] :memo: Document asar --- docs/tutorial/application-packaging.md | 36 ++++++++++++++++---------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/tutorial/application-packaging.md b/docs/tutorial/application-packaging.md index e01ecc3d9a..8e0adb9fc9 100644 --- a/docs/tutorial/application-packaging.md +++ b/docs/tutorial/application-packaging.md @@ -5,7 +5,12 @@ path names on Windows, slightly speed up `require` and conceal your source code from cursory inspection, you can choose to package your app into an [asar][asar] archive with little changes to your source code. -## Generating `asar` Archive +Most users will get this feature for free, since it's supported out of the box +by [`electron-packager`][electron-packager], [`electron-forge`][electron-forge], +and [`electron-builder`][electron-builder]. If you are not using any of these +tools, read on. + +## Generating `asar` Archives An [asar][asar] archive is a simple tar-like format that concatenates files into a single file. Electron can read arbitrary files from it without unpacking @@ -71,8 +76,9 @@ require('/path/to/example.asar/dir/module.js') You can also display a web page in an `asar` archive with `BrowserWindow`: ```javascript -const {BrowserWindow} = require('electron') -let win = new BrowserWindow({width: 800, height: 600}) +const { BrowserWindow } = require('electron') +const win = new BrowserWindow() + win.loadURL('file:///path/to/example.asar/static/index.html') ``` @@ -164,22 +170,26 @@ and `command`s are executed under shell. There is no reliable way to determine whether a command uses a file in asar archive, and even if we do, we can not be sure whether we can replace the path in command without side effects. -## Adding Unpacked Files in `asar` Archive +## Adding Unpacked Files to `asar` Archives -As stated above, some Node APIs will unpack the file to filesystem when -calling, apart from the performance issues, it could also lead to false alerts -of virus scanners. +As stated above, some Node APIs will unpack the file to the filesystem when +called. Apart from the performance issues, various anti-virus scanners might +be triggered by this behavior. -To work around this, you can unpack some files creating archives by using the -`--unpack` option, an example of excluding shared libraries of native modules -is: +As a workaround, you can leave various files unpacked using the `--unpack` option. +In the following example, shared libaries of native Node.js modules will not be +packed: ```sh $ asar pack app app.asar --unpack *.node ``` -After running the command, apart from the `app.asar`, there is also an -`app.asar.unpacked` folder generated which contains the unpacked files, you -should copy it together with `app.asar` when shipping it to users. +After running the command, you will notice that a folder named `app.asar.unpacked` +was created together with the `app.asar` file. It contains the unpacked files +and should be shipped together with the `app.asar` archive. [asar]: https://github.com/electron/asar +[electron-packager]: https://github.com/electron-userland/electron-packager +[electron-forge]: https://github.com/electron-userland/electron-forge +[electron-builder]: https://github.com/electron-userland/electron-builder +