40c3d98217
This commit introduces a new feature that enables users to run (migration) scripts.
Similar to deployment hooks, scripts are functions that may perform operations on newly
deployed Smart Contracts.
Therefore a script needs to export a function that has access to some dependencies:
```
// scripts/001-some-script.js
module.exports = async ({contracts, web3, logger}) => {
...
};
```
Where `contracts` is a map of newly deployed Smart Contract instances, `web3` a blockchain connector
instance and `logger` Embark's logger instance. Script functions can but don't have to be `async`.
To execute such a script users use the newly introduced `exec` command:
```
$ embark exec development scripts/001-some-script.js
```
In the example above, `development` defines the environment in which Smart Contracts are being
deployed to as well as where tracking data is stored.
Alternativey, users can also provide a directory in which case Embark will try to execute every
script living inside of it:
```
$ embark exec development scripts
```
Scripts can fail and therefore emit an error accordingly. When this happens, Embark will
abort the script execution (in case multiple are scheduled to run) and informs the user
about the original error:
```
.. 001_foo.js running....
Script '001_foo.js' failed to execute. Original error: Error: Some error
```
It's recommended for scripts to emit proper instances of `Error`.
(Migration) scripts can be tracked as well but there are a couple of rules to be aware of:
- Generally, tracking all scripts that have been executed by default is not a good thing because
some scripts might be one-off operations.
- OTOH, there might be scripts that should always be tracked by default
- Therefore, we introduce a dedicated `migrations` directory in which scripts live that should be
tracked by default
- Any other scripts that does not live in the specified `migrations` directory will not be tracked **unless**
- The new `--track` option was provided
For more information see: https://notes.status.im/h8XwB7xkR7GKnfNh6OnPMQ
5.2 KiB
title: Embark CLI Commands layout: docs
This is the Embark CLI command reference.
new
$ embark new dappName
Creates a new empty DApp project. If no dappName is provided, Embark will ask for the dappName.
| Option | Description |
|---|---|
--contracts-only |
create a barebones project meant only for contract development |
--simple |
an alias for --contracts-only |
--template |
DEPRECATED IN v5 download a template using a known name or a git host URL |
{% notification danger 'DEPRECATION NOTICE' %}
The --template option has been deprecated in v5 and support will be removed in future versions.
{% endnotification %}
The --template option supports several URL styles and shortcuts for git hosts:
git@github.com:ghuser/repo_name
https://github.com/ghuser/repo_name
github:ghuser/repo_name
ghuser/repo_name
It's possible to append a branch name to any of the above, for example:
https://github.com/ghuser/repo_name#branch_name
ghuser/repo_name#branch_name
Bitbucket and GitLab URLs and shortcuts are also supported, for example:
bitbucket:bbuser/repo_name#branch_name
gitlab:gluser/repo_name#branch_name
A short name can be used for templates maintained in the Embark GitHub organization, for example:
$ embark new --template typescript
demo
$ embark demo
Generates a demo Embark Project with a working contract and examples of working with contracts, IPFS and Whisper.
build
$ embark build [environment]
Deploys and Builds the DApp at dist/. If no environment is provider embark will use development by default.
run
$ embark run [environment]
Deploys and Builds the DApp at dist/. By default will launch a dashboard and start a dev server at http://localhost:8000/. If no environment is provider embark will use development by default.
| Option | Description |
|---|---|
-p, --port |
port to run the dev webserver (default: 8000) |
-b, --host |
host to run the dev webserver (default: localhost) |
--noserver |
disable the development webserver |
--nodashboard |
simple mode, disables the dashboard |
--nobrowser |
prevent the development webserver from automatically opening a web browser |
--no-color |
no colors in case it's needed for compatbility purposes |
--logfile |
filename to output logs (default: none) |
eject-build-config
$ embark eject-build-config
Copies Embark's default webpack.config.js file into your DApp so that you can customize it. If a file named webpack.config.js is present in your top-level DApp directory, Embark will use your webpack config file instead of its own.
blockchain
$ embark blockchain [environment]
Takes the config at config/blockchain.json for the environment specified and starts a blockchain node. If no environment is provider embark will use development by default.
If you want, you can skip the step of running embark blockchain, as embark run, build and upload now all start a blockchain node in a separate process if there is not one already started using the same configurations.
simulator
$ embark simulator [environment]
Takes the config at config/blockchain.json for the environment specified and starts a blockchain simulator. If no environment is provider embark will use development by default.
| Option | Description |
|---|---|
-p, --port |
port to run the rpc simulator (default: 8545) |
-h, --host |
host to run the rpc simulator (default: localhost) |
-a, --accounts |
num of accounts to start the simulator (default: 10) |
-e, --defaultBalanceEther |
balance in ether to assign each test account (default: 100) |
-l, --gasLimit |
custom gasLimit (default: 8000000) |
test
$ embark test [file]
Runs Tests. If file is not specified then it will run all the tests inside the test/ directory.
| Option | Description |
|---|---|
-n, --node |
node for running the tests (default: vm) |
-d, --gasDetails |
print the gas cost for each contract deployment when running the tests |
-c, --coverage |
generate a coverage report after running the tests (vm only) |
The --node option supports several values:
| Value | Description |
|---|---|
vm |
start and use an Ethereum simulator (ganache) |
embark |
use the node of a running embark process |
<endpoint> |
connect to and use the specified node |
Example of endpoint usage: embark test --node ws://localhost:8556
reset
$ embark reset
Resets embarks state on this dapp including clearing cache.
exec
$ embark exec [environment] [file|directory]
Executes a given (migration) script to perform complex after deployment operations.
It's required to specifiy the environment in which the script(s) will be executed in. In addition it's possible to specificy a directory in which multiple script live in. Embark will execute them one by one.
upload
$ embark upload [platform] [environment]
Uploads the DApp to a decentralized storage such as IPFS. platform can be ipfs or swarm or another parameter if supported by a plugin. If no environment is provider embark will use development by default.
graph
$ embark graph
Generates documentation based on the smart contracts configured
version
$ embark version
Displays version information.