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

Merge pull request #703 from waywardmonkeys/cleanup-asar-docs

Browse source 
[docs] Clean up some grammar around ASAR.
This commit is contained in:
Cheng Zhao 2014-10-14 18:40:47 +08:00
commit 9356296a84
2 changed files with 21 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/tutorial/application-distribution.md
View file

@ -30,10 +30,10 @@ your distribution that should be delivered to final users.
## Packaging your app into a file ## Packaging your app into a file
Apart from shipping your app by copying all its sources files, you can also Apart from shipping your app by copying all its sources files, you can also
package your app into [asar](https://github.com/atom/asar) archive to avoid package your app into an [asar](https://github.com/atom/asar) archive to avoid
exposing your app's source code to users. exposing your app's source code to users.
To use the `asar` archive to replace the `app` folder, you need to rename the To use an `asar` archive to replace the `app` folder, you need to rename the
archive to `app.asar`, and put it under atom-shell's resources directory, archive to `app.asar`, and put it under atom-shell's resources directory,
atom-shell will then try read the archive and start from it. atom-shell will then try read the archive and start from it.

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

@ -1,18 +1,18 @@
# Application packaging # Application packaging
To protect your app's resources and source code from the users, you can choose 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 to package your app into an [asar][asar] archive with little changes to your
code. source code.
## Generating `asar` archive ## Generating `asar` archive
The [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, atom-shell can read arbitrary file in it without unpacking into a single file, atom-shell can read arbitrary file in it without unpacking
the whole file. the whole file.
Following is the steps to package your app into `asar` archive: Following is the steps to package your app into an `asar` archive:
### 1. Install asar utility ### 1. Install the asar utility
```bash ```bash
$ npm install -g asar $ npm install -g asar
@ -27,13 +27,13 @@ $ asar pack your-app app.asar
## Using `asar` archives ## Using `asar` archives
In atom-shell there are two sets of APIs: Node APIs provided by Node.js, and Web 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. APIs provided by Chromium. Both APIs support reading files from `asar` archives.
### Node API ### Node API
With special patches in atom-shell, Node APIs like `fs.readFile` and `require` 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 treat `asar` archives as virtual directories, and the files in it as normal
files in filesystem. files in the filesystem.
For example, suppose we have an `example.asar` archive under `/path/to`: For example, suppose we have an `example.asar` archive under `/path/to`:
@ -47,14 +47,14 @@ $ asar list /path/to/example.asar
/static/jquery.min.js /static/jquery.min.js
``` ```
Read a file in `asar` archive: Read a file in the `asar` archive:
```javascript ```javascript
var fs = require('fs'); var fs = require('fs');
fs.readFileSync('/path/to/example.asar/file.txt'); fs.readFileSync('/path/to/example.asar/file.txt');
``` ```
List all files under the root of archive: List all files under the root of the archive:
```javascript ```javascript
var fs = require('fs'); var fs = require('fs');
@ -69,8 +69,8 @@ require('/path/to/example.asar/dir/module.js');
### Web API ### Web API
In web page files in archive can be requests by using the `asar:` protocol, In a web page, files in archive can be requested by using the `asar:` protocol.
like 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`:
@ -84,10 +84,10 @@ $.get('asar:/path/to/example.asar/file.txt', function(data) {
``` ```
The `asar:` protocol can also be used to request normal files in filesystem, 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 just like the `file:` protocol. But unlike `file:` protocol, there are no
(`//`) after `asar:`. slashes (`//`) after `asar:`.
You can also display a web page in `asar` archive with `BrowserWindow`: You can also display a web page in an `asar` archive with `BrowserWindow`:
```javascript ```javascript
var BrowserWindow = require('browser-window'); var BrowserWindow = require('browser-window');
@ -97,19 +97,19 @@ win.loadUrl('asar:/path/to/example.asar/static/index.html');
## Limitations on Node API ## Limitations on Node API
Even though we tried hard to make `asar` archives in Node API work like 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 Node API. low-level nature of the Node API.
### Archives are read only ### Archives are read only
The archives can not be modifies 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 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 to `cwd` option of some APIs will
also cause errors. also cause errors.
@ -132,7 +132,7 @@ APIs that requires extra unpacking are:
### 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 are generated by guessing, because those files do not exist on 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.