docs: Add usage on app packaging
This commit is contained in:
Cheng Zhao
parent
5a0be6672d
commit
d77bf0440c
1 changed files with 138 additions and 0 deletions
|
|
@ -1 +1,139 @@
|
|||
# Application packaging
|
||||
|
||||
To protect your app's resources and source code from the users, you can choose
|
||||
to package your app into [asar][asar] archive with little changes to your source
|
||||
code.
|
||||
|
||||
## Generating `asar` archive
|
||||
|
||||
The [asar][asar] archive is a simple tar-like format that concatenates files
|
||||
into a single file, atom-shell can read arbitrary file in it without unpacking
|
||||
the whole file.
|
||||
|
||||
Following is the steps to package your app into `asar` archive:
|
||||
|
||||
### 1. Install asar utility
|
||||
|
||||
```bash
|
||||
$ npm install -g asar
|
||||
```
|
||||
|
||||
### 2. Package with `asar pack`
|
||||
|
||||
```bash
|
||||
$ asar pack your-app app.asar
|
||||
```
|
||||
|
||||
## Using `asar` archives
|
||||
|
||||
In atom-shell there are two sets of APIs: Node APIs provided by Node.js, and Web
|
||||
APIs provided by Chromium. Both APIs support reading file from `asar` archives.
|
||||
|
||||
### Node API
|
||||
|
||||
With special patches in atom-shell, Node APIs like `fs.readFile` and `require`
|
||||
treat `asar` archives as virtual directories, and the files in it as normal
|
||||
files in filesystem.
|
||||
|
||||
For example, suppose we have an `example.asar` archive under `/path/to`:
|
||||
|
||||
```bash
|
||||
$ asar list /path/to/example.asar
|
||||
/app.js
|
||||
/file.txt
|
||||
/dir/module.js
|
||||
/static/index.html
|
||||
/static/main.css
|
||||
/static/jquery.min.js
|
||||
```
|
||||
|
||||
Read a file in `asar` archive:
|
||||
|
||||
```javascript
|
||||
var fs = require('fs');
|
||||
fs.readFileSync('/path/to/example.asar/file.txt');
|
||||
```
|
||||
|
||||
List all files under the root of archive:
|
||||
|
||||
```javascript
|
||||
var fs = require('fs');
|
||||
fs.readdirSync('/path/to/example.asar');
|
||||
```
|
||||
|
||||
Use a module from the archive:
|
||||
|
||||
```javascript
|
||||
require('/path/to/example.asar/dir/module.js');
|
||||
```
|
||||
|
||||
### Web API
|
||||
|
||||
In web page files in archive can be requests by using the `asar:` protocol,
|
||||
like node API, `asar` archives are treated as directories.
|
||||
|
||||
For example, to get a file with `$.get`:
|
||||
|
||||
```html
|
||||
<script>
|
||||
var $ = require('./jquery.min.js');
|
||||
$.get('asar:/path/to/example.asar/file.txt', function(data) {
|
||||
console.log(data);
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
The `asar:` protocol can also be used to request normal files in filesystem,
|
||||
just like the `file:` protocol. But unlike `file:` protocol, there is no slashes
|
||||
(`//`) after `asar:`.
|
||||
|
||||
You can also display a web page in `asar` archive with `BrowserWindow`:
|
||||
|
||||
```javascript
|
||||
var BrowserWindow = require('browser-window');
|
||||
var win = new BrowserWindow({width: 800, height: 600});
|
||||
win.loadUrl('asar:/path/to/example.asar/static/index.html');
|
||||
```
|
||||
|
||||
## Limitations on Node API
|
||||
|
||||
Even though we tried hard to make `asar` archives in Node API work like
|
||||
directories as much as possible, there are still limitations due to the
|
||||
low-level nature of Node API.
|
||||
|
||||
### Archives are read only
|
||||
|
||||
The archives can not be modifies so all Node APIs that can modify files will not
|
||||
work with `asar` archives.
|
||||
|
||||
### Working directory can not be set to directories in archive
|
||||
|
||||
Though `asar` archives are treated as directories, there are no actual
|
||||
directories in the filesystem, so you can never set working directory to
|
||||
directories in `asar` archives, passing them to `cwd` option of some APIs will
|
||||
also cause errors.
|
||||
|
||||
### Extra unpacking on some APIs
|
||||
|
||||
Most `fs` APIs can read file or get file's information from `asar` archives
|
||||
without unpacking, but for some APIs that rely on passing the real file path to
|
||||
underlying system calls, atom-shell will extract the needed file into a
|
||||
temporary file and pass the path of the temporary file to the APIs to make them
|
||||
work. This adds a little overhead for those APIs.
|
||||
|
||||
APIs that requires extra unpacking are:
|
||||
|
||||
* `child_process.execFile`
|
||||
* `child_process.fork`
|
||||
* `fs.open`
|
||||
* `fs.openSync`
|
||||
* `process.dlopen` - Used by `require` on native modules
|
||||
|
||||
### Fake stat information of `fs.stat`
|
||||
|
||||
The `Stats` object returned by `fs.stat` and its friends on files in `asar`
|
||||
archives are generated by guessing, because those files do not exist on
|
||||
filesystem. So you should not trust the `Stats` object except for getting file
|
||||
size and checking file type.
|
||||
|
||||
[asar]: https://github.com/atom/asar
|
||||
|
|
|
|||
Loading…
Reference in a new issue