mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

Standardize app packaging

Browse source
This commit is contained in:
Jessica Lord 2015-08-31 19:12:33 -07:00
parent e0a57a0a47
commit 96bb9b2757
1 changed files with 22 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

44
docs/tutorial/application-packaging.md
View file

@ -1,18 +1,19 @@
# Application packaging # Application Packaging
To mitigate [issues](https://github.com/joyent/node/issues/6960) around long path names on Windows, slightly speed up `require` and conceal your source code from cursory inspection you can choose To mitigate [issues](https://github.com/joyent/node/issues/6960) around long
to package your app into an [asar][asar] archive with little changes to your path names on Windows, slightly speed up `require` and conceal your source code
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 ## Generating `asar` Archive
An [asar][asar] archive is a simple tar-like format that concatenates files 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 into a single file. Electron can read arbitrary files from it without unpacking
the whole file. the whole file.
Following is the steps to package your app into an `asar` archive: Steps to package your app into an `asar` archive:
### 1. Install the asar utility ### 1. Install the asar Utility
```bash ```bash
$ npm install -g asar $ npm install -g asar
@ -24,9 +25,9 @@ $ npm install -g asar
$ asar pack your-app app.asar $ asar pack your-app app.asar
``` ```
## Using `asar` archives ## Using `asar` Archives
In Electron there are two sets of APIs: Node APIs provided by Node.js, and Web In Electron there are two sets of APIs: Node APIs provided by Node.js and Web
APIs provided by Chromium. Both APIs support reading files from `asar` archives. APIs provided by Chromium. Both APIs support reading files from `asar` archives.
### Node API ### Node API
@ -77,8 +78,8 @@ win.loadUrl('file:///path/to/example.asar/static/index.html');
### Web API ### Web API
In a web page, files in archive can be requested with the `file:` protocol. Like In a web page, files in an archive can be requested with the `file:` protocol.
the Node API, `asar` archives are treated as directories. Like the Node API, `asar` archives are treated as directories.
For example, to get a file with `$.get`: For example, to get a file with `$.get`:
@ -91,7 +92,7 @@ $.get('file:///path/to/example.asar/file.txt', function(data) {
</script> </script>
``` ```
### Treating `asar` archive as normal file ### Treating an `asar` Archive as a Normal File
For some cases like verifying the `asar` archive's checksum, we need to read the For some cases like verifying the `asar` archive's checksum, we need to read the
content of `asar` archive as file. For this purpose you can use the built-in content of `asar` archive as file. For this purpose you can use the built-in
@ -108,21 +109,21 @@ Even though we tried hard to make `asar` archives in the Node API work like
directories as much as possible, there are still limitations due to the directories as much as possible, there are still limitations due to the
low-level nature of the Node API. low-level nature of the Node API.
### Archives are read only ### Archives Are Read-only
The archives can not be modified so all Node APIs that can modify files will not The archives can not be modified so all Node APIs that can modify files will not
work with `asar` archives. work with `asar` archives.
### Working directory can not be set to directories in archive ### Working Directory Can Not Be Set to Directories in Archive
Though `asar` archives are treated as directories, there are no actual Though `asar` archives are treated as directories, there are no actual
directories in the filesystem, so you can never set the working directory to directories in the filesystem, so you can never set the working directory to
directories in `asar` archives, passing them to `cwd` option of some APIs will directories in `asar` archives. Passing them as the `cwd` option of some APIs
also cause errors. will also cause errors.
### Extra unpacking on some APIs ### Extra Unpacking on Some APIs
Most `fs` APIs can read file or get file's information from `asar` archives Most `fs` APIs can read a file or get a file's information from `asar` archives
without unpacking, but for some APIs that rely on passing the real file path to without unpacking, but for some APIs that rely on passing the real file path to
underlying system calls, Electron will extract the needed file into a underlying system calls, Electron will extract the needed file into a
temporary file and pass the path of the temporary file to the APIs to make them temporary file and pass the path of the temporary file to the APIs to make them
@ -135,14 +136,14 @@ APIs that requires extra unpacking are:
* `fs.openSync` * `fs.openSync`
* `process.dlopen` - Used by `require` on native modules * `process.dlopen` - Used by `require` on native modules
### Fake stat information of `fs.stat` ### Fake Stat Information of `fs.stat`
The `Stats` object returned by `fs.stat` and its friends on files in `asar` The `Stats` object returned by `fs.stat` and its friends on files in `asar`
archives is generated by guessing, because those files do not exist on the archives is generated by guessing, because those files do not exist on the
filesystem. So you should not trust the `Stats` object except for getting file filesystem. So you should not trust the `Stats` object except for getting file
size and checking file type. size and checking file type.
## Adding unpacked files in `asar` archive ## Adding Unpacked Files in `asar` Archive
As stated above, some Node APIs will unpack the file to filesystem when 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 calling, apart from the performance issues, it could also lead to false alerts
@ -161,4 +162,3 @@ After running the command, apart from the `app.asar`, there is also an
should copy it together with `app.asar` when shipping it to users. should copy it together with `app.asar` when shipping it to users.
[asar]: https://github.com/atom/asar [asar]: https://github.com/atom/asar