update docs

This commit is contained in:
Iuri Matias 2018-03-15 16:11:42 -04:00
parent db89798fb4
commit 93b636036d
13 changed files with 313 additions and 31 deletions

View File

@ -14,7 +14,10 @@ e.g :
"provider": "ipfs", "provider": "ipfs",
"available_providers": ["ipfs"], "available_providers": ["ipfs"],
"host": "localhost", "host": "localhost",
"port": 5001 "port": 5001,
"versions": {
"ipfs-api": "17.2.4"
}
}, },
"development": { "development": {
"enabled": true, "enabled": true,
@ -30,4 +33,5 @@ options available:
* ``provider`` (string: "ipfs") desired provider to automatically connect to on the dapp. e.g in the example above, seting this to ``"ipfs"`` will automaticaly add ``EmbarkJS.setProvider('ipfs', {server: 'localhost', 5001})`` to the generated code * ``provider`` (string: "ipfs") desired provider to automatically connect to on the dapp. e.g in the example above, seting this to ``"ipfs"`` will automaticaly add ``EmbarkJS.setProvider('ipfs', {server: 'localhost', 5001})`` to the generated code
* ``available_providers`` (array: ["ipfs"]) list of storages to be supported on the dapp. This will affect what's available with the EmbarkJS library on the dapp. * ``available_providers`` (array: ["ipfs"]) list of storages to be supported on the dapp. This will affect what's available with the EmbarkJS library on the dapp.
* ``host`` and ``port`` of the ipfs node to connect to. * ``host`` and ``port`` of the ipfs node to connect to.
* ``versions`` (object) key-value hash of library and its desired version

View File

@ -25,11 +25,8 @@ DApp Structure
.. code:: bash .. code:: bash
app/ app/ # dapp code
|___ contracts/ #solidity smart contracts contracts/ #smart contracts
|___ html/
|___ css/
|___ js/
config/ config/
|___ blockchain.json #rpc and blockchain configuration |___ blockchain.json #rpc and blockchain configuration
|___ contracts.json #ethereum contracts configuration |___ contracts.json #ethereum contracts configuration
@ -38,5 +35,9 @@ DApp Structure
|___ webserver.json #dev webserver configuration |___ webserver.json #dev webserver configuration
test/ test/
|___ #contracts tests |___ #contracts tests
dist/
|___ # build folder
chains.json #keeps track of deployments in each chain
Solidity files in the contracts directory will automatically be deployed with ``embark run``. Changes in any files will automatically be reflected in app, changes to contracts will result in a redeployment and update of their JS Bindings Solidity files in the contracts directory will automatically be deployed with ``embark run``. Changes in any files will automatically be reflected in app, changes to contracts will result in a redeployment and update of their JS Bindings

View File

@ -28,3 +28,19 @@ Embark.
if you prefer to only see the logs, you can disable the dashboard with the if you prefer to only see the logs, you can disable the dashboard with the
nodashboard option ``embark run --nodashboard`` nodashboard option ``embark run --nodashboard``
Console
=========
There is a console at the bottom which can be used to interact with
contracts or with embark itself. type ``help`` to see a list of
available commands, more commands will be added with each version of
Embark.
After contract deployment, you should be able to interact with the web3 object and the deployed contracts.
Some commands available include:
* ``version`` - see list of software & libraries and their respective versions
* ``quit`` or ``exit`` - to immediatly exit (you can also use ctrl + c)
* ``webserver start`` - start the dev webserver
* ``webserver stop`` - stop the dev webserver

View File

@ -6,3 +6,4 @@ and then run ``embark upload ipfs``. If you want to deploy to the livenet then
after configuring you account on ``config/blockchain.json`` on the after configuring you account on ``config/blockchain.json`` on the
``livenet`` environment then you can deploy to that chain by ``livenet`` environment then you can deploy to that chain by
specifying the environment ``embark ipfs livenet``. specifying the environment ``embark ipfs livenet``.

View File

@ -55,3 +55,8 @@ The current available storage is IPFS. it can be initialized as
.. code:: javascript .. code:: javascript
EmbarkJS.Storage.getUrl(hash); EmbarkJS.Storage.getUrl(hash);
**configuring IPFS**
note: if not using localhost, the cors needs to be set as ```ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["your-host-name-port"]```

View File

@ -29,6 +29,7 @@ This is a work in progress, feel free to contribute!
deploying-to-swarm.rst deploying-to-swarm.rst
plugins.rst plugins.rst
using-embark-with-grunt.rst using-embark-with-grunt.rst
other.rst
donations.rst donations.rst
Indices and tables Indices and tables

8
docs/other.rst Normal file
View File

@ -0,0 +1,8 @@
Other
========
In case you run into issues it can useful to reset embark's state, to do this
you can run the cmd ```embark reset```

View File

@ -28,13 +28,16 @@ The ``embark`` object then provides an api to extend different functionality of
* plugin to add support for es6, jsx, coffescript, etc (``embark.registerPipeline``) * plugin to add support for es6, jsx, coffescript, etc (``embark.registerPipeline``)
* plugin to add standard contracts or a contract framework (``embark.registerContractConfiguration`` and ``embark.addContractFile``) * plugin to add standard contracts or a contract framework (``embark.registerContractConfiguration`` and ``embark.addContractFile``)
* plugin to make some contracts available in all environments for use by other contracts or the dapp itself e.g a Token, a DAO, ENS, etc.. (``embark.registerContractConfiguration`` and ``embark.addContractFile``) * plugin to make some contracts available in all environments for use by other contracts or the dapp itself e.g a Token, a DAO, ENS, etc.. (``embark.registerContractConfiguration`` and ``embark.addContractFile``)
* plugin to add a libraries such as react or boostrap (``embark.addFileToPipeline``) * plugin to add a libraries such as react or boostrap (``embark.addFileToPipeline``, ``embark.registerImportFile``)
* plugin to process contract's binary code before deployment (``embark.beforeDeploy``) * plugin to process contract's binary code before deployment (``embark.beforeDeploy``)
* plugin to specify a particular web3 initialization for special provider uses (``embark.registerClientWeb3Provider``) * plugin to specify a particular web3 initialization for special provider uses (``embark.registerClientWeb3Provider``)
* plugin to create a different contract wrapper (``embark.registerContractsGeneration``) * plugin to create a different contract wrapper (``embark.registerContractsGeneration``)
* plugin to add new console commands (``embark.registerConsoleCommand``) * plugin to add new console commands (``embark.registerConsoleCommand``)
* plugin to add support for another contract language such as viper, LLL, etc (``embark.registerCompiler``) * plugin to add support for another contract language such as viper, LLL, etc (``embark.registerCompiler``)
* plugin that executes certain actions when contracts are deployed (``embark.events.on``) * plugin that executes certain actions when contracts are deployed (``embark.events.on``)
* plugin that registers a service in embark (``embark.registerServiceCheck``)
* plugin that adds support to upload the dapp somewhere (``embark.registerUploadCommand``)
* plugin that extends EmbarkJS (``embark.addCodeToEmbarkJS``, ``embark.addProviderInit``)
**embark.pluginConfig** **embark.pluginConfig**
@ -298,9 +301,11 @@ This call is used to listen and react to events that happen in Embark such as co
* available events: * available events:
* "contractsDeployed" - triggered when contracts have been deployed * "contractsDeployed" - triggered when contracts have been deployed
* "file-add", "file-change", "file-remove", "file-event" - triggered on a file change, args is (filetype, path) * "file-add", "file-change", "file-remove", "file-event" - triggered on a file change, args is (filetype, path)
* "abi", "abi-vanila", "abi-contracts-vanila" - triggered when contracts have been deployed and returns the generated JS code * "code", "code-vanila", "code-contracts-vanila" - triggered when contracts have been deployed and returns the generated JS code
* "outputDone" - triggered when dapp is (re)generated * "outputDone" - triggered when dapp is (re)generated
* "firstDeploymentDone" - triggered when the dapp is deployed and generated for the first time * "firstDeploymentDone" - triggered when the dapp is deployed and generated for the first time
* "check:backOnline:serviceName" - triggered when the service with ``serviceName`` comes back online
* "check:backOffline:serviceName" - triggered when the service with ``serviceName`` comes back offline
.. code:: javascript .. code:: javascript
@ -314,3 +319,85 @@ This call is used to listen and react to events that happen in Embark such as co
} }
}); });
} }
**embark.registerServiceCheck(serviceName, callback({name, status}), time)**
This call is used to register a service in embark so it's periodically checked.
It will be displayed in the Embark Dashboard, and will also trigger events such as ``check:backOnline:yourServiceName`` and ``check:backOffline:yourServiceName``
* serviceName - name of service (string)
* callback:
* "name" - name/text to display (string)
* "status" - status of the service (string, "on" or "off" or "warn")
* time (optional) - ms interval to call the callback (default: 5000 ms)
.. code:: javascript
module.exports = function(embark) {
embark.registerServiceCheck("MyServer", function(cb) {
if (myServiceOnline()) {
return cb({name: "MyServer Online", status: "on"});
} else {
return cb({name: "MyServer Offline", status: "off"});
}
});
}
**embark.registerUploadCommand(cmdName, callback)**
This call is used to add a new cmd to ``embark upload`` to upload the dapp to
a new storage service
.. code:: javascript
module.exports = function(embark) {
embark.registerUploadCommand("ipfs", function() {
run("ipfs add -r dist/");
});
}
**embark.addCodeToEmbarkJS(code)**
This call is used to add code to the embark.js library. It's typically used to
extend it with new functionality, new storage providers, new communication
providers, etc..
.. code:: javascript
module.exports = function(embark) {
embark.addCodeToEmbarkJS("alert('hello world!')");
}
**embark.addProviderInit(providerType, code, initCondition(config))**
This call is used to add code to be executed in the initialization under the
condition that ```initCondition``` returns true. For example this can be used to
set the storage provider of EmbarkJS to ipfs if ipfs is enabled as a provider in
the config
* providerType - type of provider (string, "storage" or "communication")
* code - code to add (string)
* callback:
* "config" - config of the ``providerType``
.. code:: javascript
module.exports = function(embark) {
let code = "\nEmbarkJS.Storage.setProvider('ipfs')";
embark.addProviderInit('storage', code, (storageConfig) => {
return (storageConfig.provider === 'ipfs' && storageConfig.enabled === true);
});
}
**embark.registerImportFile(importName, importLocation)**
This call is used so the plugin can make a certain file available as a library
to a user
.. code:: javascript
var path = require('path')
module.exports = function(embark) {
embark.registerImportFile("my-lib", path.join(__dirname, "my-lib.js"));
}

View File

@ -8,12 +8,12 @@ structure using ``embark.json``
# embark.json # embark.json
{ {
"contracts": ["app/contracts/**"], "contracts": ["contracts/**"],
"app": { "app": {
"js/app.js": ["app/dapp.js"],
"index.html": "app/index.html",
"css/app.css": ["app/css/**"], "css/app.css": ["app/css/**"],
"images/": ["app/images/**"], "images/": ["app/images/**"]
"js/app.js": ["embark.js", "app/js/**"],
"index.html": "app/index.html"
}, },
"buildDir": "dist/", "buildDir": "dist/",
"config": "config/", "config": "config/",

View File

@ -10,20 +10,17 @@ EVM.
.. code:: javascript .. code:: javascript
# test/simple_storage_spec.js # test/simple_storage_spec.js
var assert = require('assert');
var Embark = require('embark');
var EmbarkSpec = Embark.initTests();
var web3 = EmbarkSpec.web3;
describe("SimpleStorage", function() { describe("SimpleStorage", function() {
this.timeout(0);
before(function(done) { before(function(done) {
var contractsConfig = { var contractsConfig = {
"SimpleStorage": { "SimpleStorage": {
args: [100] args: [100]
} }
}; };
EmbarkSpec.deployAll(contractsConfig, done); EmbarkSpec.deployAll(contractsConfig, (accounts) => {
done();
});
}); });
it("should set constructor value", function(done) { it("should set constructor value", function(done) {
@ -44,5 +41,82 @@ EVM.
}); });
**configuring accounts**
You can use a mnemonic to always use a specific account for testing purposes
.. code:: javascript
# test/simple_storage_spec.js
config({
mnemonic: "labor ability deny divide mountain buddy home client type shallow outer pen"
})
describe("SimpleStorage", function() {
....
**configuring node**
By default Embark will use an internal VM to run the tests, however you can also
specify a node to connect to and run the tests there.
.. code:: javascript
# test/simple_storage_spec.js
config({
node: "http://localhost:8545"
})
describe("SimpleStorage", function() {
....
**testing with any testing framework**
Embark uses `Mocha <http://mochajs.org/>`__ by default, but you can use Embark uses `Mocha <http://mochajs.org/>`__ by default, but you can use
any testing framework you want. any testing framework you want. To do this you can require Embark as a library
and initialize the testing functionality. Below is an example using mocha:
.. code:: javascript
# test/simple_storage_spec.js
var assert = require('assert');
var Embark = require('embark');
var EmbarkSpec = Embark.initTests();
var web3 = EmbarkSpec.web3;
describe("SimpleStorage", function() {
this.timeout(0);
before(function(done) {
var contractsConfig = {
"SimpleStorage": {
args: [100]
}
};
EmbarkSpec.deployAll(contractsConfig, (accounts) => {
done();
});
});
it("should set constructor value", function(done) {
SimpleStorage.storedData(function(err, result) {
assert.equal(result.toNumber(), 100);
done();
});
});
it("set storage value", function(done) {
SimpleStorage.set(150, function() {
SimpleStorage.get(function(err, result) {
assert.equal(result.toNumber(), 150);
done();
});
});
});
});
``mocha test/simple_storage_spec.js --no-timeouts``

View File

@ -42,3 +42,36 @@ and deploy your DApp to a local server at http://localhost:8000
Note that if you update your code it will automatically be re-deployed, Note that if you update your code it will automatically be re-deployed,
contracts included. There is no need to restart embark, refreshing the contracts included. There is no need to restart embark, refreshing the
page on the browser will do. page on the browser will do.
embark run options
============
**Dashboard**
* ``--nodashboard`` - simple mode, disables the dashboard
* ``--no-color`` - no colors in case it's needed for compatbility purposes
**Web Server**
* ``-p [port]`` or ``--port [port]`` - port to run the dev webserver (default: 8000)
* ``-b [host]`` or ``--host [host]`` - host to run the dev webserver (default: localhost)
* ``--noserver`` - disable the development webserver
**Log File**
* ``--logfile [logfile]`` - filename to output logs (default: none)
embark simulator options
============
**RPC Server**
* ``-p [port]`` or ``--port [port]`` - port to run the rpc simulator (default: 8545)
* ``-b [host]`` or ``--host [host]`` - host to run the rpc simulator (default: localhost)
**Other Options**
* ``--accounts [numAccounts]`` - number of accounts (default: 10)
* ``--defaultBalanceEther [balance]`` - Amount of ether to assign each test account (default: 100)
* ``--gasLimit [gasLimit]`` - custom gas limit (default: 8000000)

View File

@ -27,9 +27,11 @@ Will automatically be available in Javascript as:
.. code:: javascript .. code:: javascript
# app/js/index.js # app/js/index.js
SimpleStorage.set(100); import SimpleStorage from 'Embark/contracts/SimpleStorage';
SimpleStorage.get().then(function(value) { console.log(value.toNumber()) });
SimpleStorage.storedData().then(function(value) { console.log(value.toNumber()) }); SimpleStorage.methods.set(100).send();
SimpleStorage.methods.get().call().then(function(value) { console.log(value) });
SimpleStorage.methods.storedData().call().then(function(value) { console.log(value) });
You can specify for each contract and environment its gas costs and You can specify for each contract and environment its gas costs and
arguments: arguments:
@ -44,7 +46,8 @@ arguments:
"SimpleStorage": { "SimpleStorage": {
"args": [ "args": [
100 100
] ],
"gas": 800000
} }
} }
} }
@ -53,6 +56,7 @@ arguments:
If you are using multiple contracts, you can pass a reference to another If you are using multiple contracts, you can pass a reference to another
contract as ``$ContractName``, Embark will automatically replace this contract as ``$ContractName``, Embark will automatically replace this
with the correct address for the contract. with the correct address for the contract.
You can also specify interfaces and choose to not deploy contracts (for e.g in case they are interfaces)
.. code:: json .. code:: json
@ -76,6 +80,9 @@ with the correct address for the contract.
"args": [ "args": [
"$SimpleStorage" "$SimpleStorage"
] ]
},
"MyContractInteface": {
"deploy": false
} }
} }
} }
@ -169,3 +176,4 @@ instead.
} }
... ...
} }

View File

@ -19,8 +19,52 @@ managed at config/blockchain.json
"rpcHost": "localhost", "rpcHost": "localhost",
"rpcPort": 8545, "rpcPort": 8545,
"rpcCorsDomain": "http://localhost:8000", "rpcCorsDomain": "http://localhost:8000",
"account": {
"password": "config/livenet/password"
},
"targetGasLimit": 8000000,
"wsOrigins": "http://localhost:8000",
"wsRPC": true,
"wsHost": "localhost",
"wsPort": 8546,
"simulatorMnemonic": "example exile argue silk regular smile grass bomb merge arm assist farm",
"simulatorBlocktime": 0
},
...
**Specify a genesis block**
You can specify a genesis block for each environment if you so wish. This can be
useful to establish some initial balances and specific conditions such as the
gasLimit
.. code:: json
# config/blockchain.json
...
"development": {
"genesisBlock": "config/development/genesis.json",
"account": { "account": {
"password": "config/livenet/password" "password": "config/livenet/password"
} }
}, },
... ...
# config/development/genesis.json
{
"config": {
"homesteadBlock": 1
},
"nonce": "0x0000000000000042",
"difficulty": "0x0",
"alloc": {
"0x3333333333333333333333333333333333333333": {"balance": "15000000000000000000"}
},
"mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"coinbase": "0x3333333333333333333333333333333333333333",
"timestamp": "0x00",
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"extraData": "0x",
"gasLimit": "0x7a1200"
}