diff --git a/docs/tutorial/application-distribution.md b/docs/tutorial/application-distribution.md index 72d78bc9b253..8258028f2f4b 100644 --- a/docs/tutorial/application-distribution.md +++ b/docs/tutorial/application-distribution.md @@ -30,10 +30,10 @@ your distribution that should be delivered to final users. ## Packaging your app into a file 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. -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, atom-shell will then try read the archive and start from it. diff --git a/docs/tutorial/application-packaging.md b/docs/tutorial/application-packaging.md index 0303969d6767..423162443fd7 100644 --- a/docs/tutorial/application-packaging.md +++ b/docs/tutorial/application-packaging.md @@ -1,18 +1,18 @@ # 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. +to package your app into an [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 +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 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 $ npm install -g asar @@ -27,13 +27,13 @@ $ 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. +APIs provided by Chromium. Both APIs support reading files 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. +files in the filesystem. 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 ``` -Read a file in `asar` archive: +Read a file in the `asar` archive: ```javascript var fs = require('fs'); 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 var fs = require('fs'); @@ -69,8 +69,8 @@ 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. +In a web page, files in archive can be requested by using the `asar:` protocol. +Like the Node API, `asar` archives are treated as directories. 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, -just like the `file:` protocol. But unlike `file:` protocol, there is no slashes -(`//`) after `asar:`. +just like the `file:` protocol. But unlike `file:` protocol, there are no +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 var BrowserWindow = require('browser-window'); @@ -97,19 +97,19 @@ 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 +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 -low-level nature of Node API. +low-level nature of the Node API. ### 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. ### 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 the filesystem, so you can never set the working directory to directories in `asar` archives, passing them to `cwd` option of some APIs will also cause errors. @@ -132,7 +132,7 @@ APIs that requires extra unpacking are: ### 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 +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 size and checking file type.