mirror of
https://github.com/tiennm99/FBcount.git
synced 2026-10-03 09:58:33 +00:00
Init
This commit is contained in:
MiTiX committed
1 parent
f2c263eefa
commit
2ae7118139
4280 files changed
+484929
No files matched your search
+233
@@ -0,0 +1,233 @@
|
||||
**Disclaimer: `pkg` was created for use within containers and is not intended for use in serverless environments. For those using ZEIT Now, this means that there is no requirement to use `pkg` in your projects as the benefits it provides are not applicable to the platform.**
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[](https://travis-ci.org/zeit/pkg)
|
||||
[](https://coveralls.io/github/zeit/pkg?branch=master)
|
||||
[](https://david-dm.org/zeit/pkg)
|
||||
[](https://david-dm.org/zeit/pkg?type=dev)
|
||||
[](https://spectrum.chat/zeit)
|
||||
|
||||
This command line interface enables you to package your Node.js project into an executable that can be run even on devices without Node.js installed.
|
||||
|
||||
## Use Cases
|
||||
|
||||
* Make a commercial version of your application without sources
|
||||
* Make a demo/evaluation/trial version of your app without sources
|
||||
* Instantly make executables for other platforms (cross-compilation)
|
||||
* Make some kind of self-extracting archive or installer
|
||||
* No need to install Node.js and npm to run the packaged application
|
||||
* No need to download hundreds of files via `npm install` to deploy
|
||||
your application. Deploy it as a single file
|
||||
* Put your assets inside the executable to make it even more portable
|
||||
* Test your app against new Node.js version without installing it
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
npm install -g pkg
|
||||
```
|
||||
|
||||
After installing it, run `pkg --help` without arguments to see list of options.
|
||||
|
||||
The entrypoint of your project is a mandatory CLI argument. It may be:
|
||||
|
||||
* Path to entry file. Suppose it is `/path/app.js`, then
|
||||
packaged app will work the same way as `node /path/app.js`
|
||||
* Path to `package.json`. `Pkg` will follow `bin` property of
|
||||
the specified `package.json` and use it as entry file.
|
||||
* Path to directory. `Pkg` will look for `package.json` in
|
||||
the specified directory. See above.
|
||||
|
||||
### Targets
|
||||
|
||||
`pkg` can generate executables for several target machines at a
|
||||
time. You can specify a comma-separated list of targets via `--targets`
|
||||
option. A canonical target consists of 3 elements, separated by
|
||||
dashes, for example `node6-macos-x64` or `node4-linux-armv6`:
|
||||
|
||||
* **nodeRange** node${n} or latest
|
||||
* **platform** freebsd, linux, alpine, macos, win
|
||||
* **arch** x64, x86, armv6, armv7
|
||||
|
||||
You may omit any element (and specify just `node6` for example).
|
||||
The omitted elements will be taken from current platform or
|
||||
system-wide Node.js installation (its version and arch).
|
||||
There is also an alias `host`, that means that all 3 elements
|
||||
are taken from current platform/Node.js. By default targets are
|
||||
`linux,macos,win` for current Node.js version and arch.
|
||||
|
||||
### Config
|
||||
|
||||
During packaging process `pkg` parses your sources, detects
|
||||
calls to `require`, traverses the dependencies of your project
|
||||
and includes them into executable. In most cases you
|
||||
don't need to specify anything manually. However your code
|
||||
may have `require(variable)` calls (so called non-literal
|
||||
argument to `require`) or use non-javascript files (for
|
||||
example views, css, images etc).
|
||||
```js
|
||||
require('./build/' + cmd + '.js')
|
||||
path.join(__dirname, 'views/' + viewName)
|
||||
```
|
||||
Such cases are not handled by `pkg`. So you must specify the
|
||||
files - scripts and assets - manually in `pkg` property of
|
||||
your `package.json` file.
|
||||
```json
|
||||
"pkg": {
|
||||
"scripts": "build/**/*.js",
|
||||
"assets": "views/**/*"
|
||||
}
|
||||
```
|
||||
You may also specify arrays of globs:
|
||||
```
|
||||
"assets": [ "assets/**/*", "images/**/*" ]
|
||||
```
|
||||
Just be sure to call `pkg package.json` or `pkg .` to make use
|
||||
of `scripts` and `assets` entries.
|
||||
|
||||
### Scripts
|
||||
|
||||
`scripts` is a [glob](https://github.com/sindresorhus/globby)
|
||||
or list of globs. Files specified as `scripts` will be compiled
|
||||
using `v8::ScriptCompiler` and placed into executable without
|
||||
sources. They must conform to the JS standards of those Node.js versions
|
||||
you target (see [Targets](#targets)), i.e. be already transpiled.
|
||||
|
||||
### Assets
|
||||
|
||||
`assets` is a [glob](https://github.com/sindresorhus/globby)
|
||||
or list of globs. Files specified as `assets` will be packaged
|
||||
into executable as raw content without modifications. Javascript
|
||||
files may also be specified as `assets`. Their sources will
|
||||
not be stripped as it improves execution performance of the
|
||||
files and simplifies debugging.
|
||||
|
||||
See also
|
||||
[Detecting assets in source code](#detecting-assets-in-source-code) and
|
||||
[Snapshot filesystem](#snapshot-filesystem).
|
||||
|
||||
### Options
|
||||
|
||||
Node.js application can be called with runtime options
|
||||
(belonging to Node.js or V8). To list them type `node --help` or
|
||||
`node --v8-options`. You can "bake" these runtime options into
|
||||
packaged application. The app will always run with the options
|
||||
turned on. Just remove `--` from option name.
|
||||
```sh
|
||||
pkg app.js --options expose-gc
|
||||
pkg app.js --options max_old_space_size=4096
|
||||
```
|
||||
|
||||
### Output
|
||||
|
||||
You may specify `--output` if you create only one executable
|
||||
or `--out-path` to place executables for multiple targets.
|
||||
|
||||
### Debug
|
||||
|
||||
Pass `--debug` to `pkg` to get a log of packaging process.
|
||||
If you have issues with some particular file (seems not packaged
|
||||
into executable), it may be useful to look through the log.
|
||||
|
||||
### Build
|
||||
|
||||
`pkg` has so called "base binaries" - they are actually same
|
||||
`node` executables but with some patches applied. They are
|
||||
used as a base for every executable `pkg` creates. `pkg`
|
||||
downloads precompiled base binaries before packaging your
|
||||
application. If you prefer to compile base binaries from
|
||||
source instead of downloading them, you may pass `--build`
|
||||
option to `pkg`. First ensure your computer meets the
|
||||
requirements to compile original Node.js:
|
||||
[BUILDING.md](https://github.com/nodejs/node/blob/master/BUILDING.md)
|
||||
|
||||
## Usage of packaged app
|
||||
|
||||
Command line call to packaged app `./app a b` is equivalent
|
||||
to `node app.js a b`
|
||||
|
||||
## Snapshot filesystem
|
||||
|
||||
During packaging process `pkg` collects project files and places
|
||||
them into executable. It is called a snapshot. At run time the
|
||||
packaged application has access to snapshot filesystem where all
|
||||
that files reside.
|
||||
|
||||
Packaged files have `/snapshot/` prefix in their paths (or
|
||||
`C:\snapshot\` in Windows). If you used `pkg /path/app.js` command line,
|
||||
then `__filename` value will be likely `/snapshot/path/app.js`
|
||||
at run time. `__dirname` will be `/snapshot/path` as well. Here is
|
||||
the comparison table of path-related values:
|
||||
|
||||
value | with `node` | packaged | comments
|
||||
-------------------------------|---------------------|----------------------------|-----------
|
||||
__filename | /project/app.js | /snapshot/project/app.js |
|
||||
__dirname | /project | /snapshot/project |
|
||||
process.cwd() | /project | /deploy | suppose the app is called ...
|
||||
process.execPath | /usr/bin/nodejs | /deploy/app-x64 | `app-x64` and run in `/deploy`
|
||||
process.argv[0] | /usr/bin/nodejs | /deploy/app-x64 |
|
||||
process.argv[1] | /project/app.js | /snapshot/project/app.js |
|
||||
process.pkg.entrypoint | undefined | /snapshot/project/app.js |
|
||||
process.pkg.defaultEntrypoint | undefined | /snapshot/project/app.js |
|
||||
require.main.filename | /project/app.js | /snapshot/project/app.js |
|
||||
|
||||
Hence, in order to make use of a file collected at packaging
|
||||
time (`require` a javascript file or serve an asset) you should
|
||||
take `__filename`, `__dirname`, `process.pkg.defaultEntrypoint`
|
||||
or `require.main.filename` as a base for your path calculations.
|
||||
For javascript files you can just `require` or `require.resolve`
|
||||
because they use current `__dirname` by default. For assets use
|
||||
`path.join(__dirname, '../path/to/asset')`. Learn more about
|
||||
`path.join` in
|
||||
[Detecting assets in source code](#detecting-assets-in-source-code).
|
||||
|
||||
On the other hand, in order to access real file system at run time
|
||||
(pick up a user's external javascript plugin, json configuration or
|
||||
even get a list of user's directory) you should take `process.cwd()`
|
||||
or `path.dirname(process.execPath)`.
|
||||
|
||||
## Detecting assets in source code
|
||||
|
||||
When `pkg` encounters `path.join(__dirname, '../path/to/asset')`,
|
||||
it automatically packages the file specified as an asset. See
|
||||
[Assets](#assets). Pay attention that `path.join` must have two
|
||||
arguments and the last one must be a string literal.
|
||||
|
||||
This way you may even avoid creating `pkg` config for your project.
|
||||
|
||||
## Native addons
|
||||
|
||||
Native addons (`.node` files) use is supported, but packaging
|
||||
`.node` files inside the executable is not resolved yet. You have
|
||||
to deploy native addons used by your project to the same directory
|
||||
as the executable.
|
||||
|
||||
When a package, that contains a native module, is being installed,
|
||||
the native module is compiled against current system-wide Node.js
|
||||
version. Then, when you compile your project with `pkg`, pay attention
|
||||
to `--target` option. You should specify the same Node.js version
|
||||
as your system-wide Node.js to make compiled executable compatible
|
||||
with `.node` files.
|
||||
|
||||
## API
|
||||
|
||||
`const { exec } = require('pkg')`
|
||||
|
||||
`exec(args)` takes an array of command line arguments and returns
|
||||
a promise. For example:
|
||||
|
||||
```js
|
||||
await exec([ 'app.js', '--target', 'host', '--output', 'app.exe' ])
|
||||
// do something with app.exe, run, test, upload, deploy, etc
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: ENOENT: no such file or directory, uv_chdir
|
||||
|
||||
This error can be caused by deleting the directory the application is
|
||||
run from. Or, generally, deleting `process.cwd()` directory when the
|
||||
application is running.
|
||||
Reference in new issue
Block a user