From 17a64d9559e3b8d792f0f9493fec2e6bca577535 Mon Sep 17 00:00:00 2001 From: Iuri Matias Date: Sat, 14 Jan 2017 18:11:43 -0500 Subject: [PATCH] update docs and readme --- README.md | 9 +- dapp-structure.md | 0 docs/conf.py | 6 +- docs/creating-a-new-dapp.rst | 30 +++++ docs/dashboard.rst | 24 ++++ docs/deploying-to-ipfs.rst | 8 ++ docs/deploying-to-swarm.rst | 4 + docs/donations.md | 4 + docs/donations.rst | 5 + docs/embarkjs-communication.rst | 46 +++++++ docs/embarkjs-storage.rst | 39 ++++++ docs/embarkjs.rst | 30 +++++ docs/index.rst | 17 ++- docs/installation.rst | 24 ++++ docs/libraries-and-languages-available.rst | 14 +++ docs/structuring-application.rst | 19 +++ docs/tests.rst | 48 +++++++ docs/usage.rst | 44 +++++++ docs/using-contracts.rst | 138 +++++++++++++++++++++ docs/working-with-different-chains.rst | 26 ++++ libraries-and-languages-available.md | 0 21 files changed, 524 insertions(+), 11 deletions(-) create mode 100644 dapp-structure.md create mode 100644 docs/creating-a-new-dapp.rst create mode 100644 docs/dashboard.rst create mode 100644 docs/deploying-to-ipfs.rst create mode 100644 docs/deploying-to-swarm.rst create mode 100644 docs/donations.md create mode 100644 docs/donations.rst create mode 100644 docs/embarkjs-communication.rst create mode 100644 docs/embarkjs-storage.rst create mode 100644 docs/embarkjs.rst create mode 100644 docs/installation.rst create mode 100644 docs/libraries-and-languages-available.rst create mode 100644 docs/structuring-application.rst create mode 100644 docs/tests.rst create mode 100644 docs/usage.rst create mode 100644 docs/using-contracts.rst create mode 100644 docs/working-with-different-chains.rst create mode 100644 libraries-and-languages-available.md diff --git a/README.md b/README.md index e8ec16ce..1c7b0da6 100644 --- a/README.md +++ b/README.md @@ -480,16 +480,13 @@ Embark is quite flexible and you can configure you're own directory structure us } ``` -Deploying to IPFS +Deploying to IPFS and Swarm ====== -To deploy a dapp to IPFS, all you need to do is run a local IPFS node and then run ```embark ipfs```. +To deploy a dapp to IPFS, all you need to do is run a local IPFS node 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 ```production``` environment then you can deploy to that chain by specifying the environment ```embark ipfs production```. -LiveReload Plugin -====== - -Embark works quite well with the LiveReload Plugin +To deploy a dapp to SWARM, all you need to do is run a local SWARM node and then run ```embark upload swarm```. Donations ====== diff --git a/dapp-structure.md b/dapp-structure.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/conf.py b/docs/conf.py index 2cf6c12a..fce483a5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,8 +50,8 @@ master_doc = 'index' # General information about the project. project = u'Embark' -copyright = u'2017, Iuri Matias ' -author = u'Iuri Matias ' +copyright = u'2017, Iuri Matias' +author = u'Iuri Matias' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -131,7 +131,7 @@ latex_elements = { # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'Embark.tex', u'Embark Documentation', - u'Iuri Matias \\textless{}iuri.matias@gmail.com\\textgreater{}', 'manual'), + u'Iuri Matias \\textless{}\\textgreater{}', 'manual'), ] diff --git a/docs/creating-a-new-dapp.rst b/docs/creating-a-new-dapp.rst new file mode 100644 index 00000000..dd39a082 --- /dev/null +++ b/docs/creating-a-new-dapp.rst @@ -0,0 +1,30 @@ +Creating a new DApp +=================== + +If you want to create a blank new app. + +.. code:: bash + + $ embark new AppName + $ cd AppName + +DApp Structure +============== + +.. code:: bash + + app/ + |___ contracts/ #solidity or serpent contracts + |___ html/ + |___ css/ + |___ js/ + config/ + |___ blockchain.json #environments configuration + |___ contracts.json #contracts configuration + test/ + |___ #contracts tests + +Solidity/Serpent 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 diff --git a/docs/dashboard.rst b/docs/dashboard.rst new file mode 100644 index 00000000..c6b395cd --- /dev/null +++ b/docs/dashboard.rst @@ -0,0 +1,24 @@ +Dashboard +========= + +Embark 2 comes with a terminal dashboard. + +.. figure:: http://i.imgur.com/s4OQZpu.jpg + :alt: Dashboard + + Dashboard + +The dashboard will tell you the state of your contracts, the enviroment +you are using, and what embark is doing at the moment. + +**available services** + +Available Services will display the services available to your dapp in +green, if one of these is down then it will be displayed in red. + +**logs and 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. diff --git a/docs/deploying-to-ipfs.rst b/docs/deploying-to-ipfs.rst new file mode 100644 index 00000000..a0da4f72 --- /dev/null +++ b/docs/deploying-to-ipfs.rst @@ -0,0 +1,8 @@ +Deploying to IPFS +================= + +To deploy a dapp to IPFS, all you need to do is run a local IPFS node +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 +``production`` environment then you can deploy to that chain by +specifying the environment ``embark ipfs production``. diff --git a/docs/deploying-to-swarm.rst b/docs/deploying-to-swarm.rst new file mode 100644 index 00000000..5182d92d --- /dev/null +++ b/docs/deploying-to-swarm.rst @@ -0,0 +1,4 @@ +Deploying to SWARM +================= + +To deploy a dapp to SWARM, all you need to do is run a local SWARM node and then run ``embark upload swarm``. diff --git a/docs/donations.md b/docs/donations.md new file mode 100644 index 00000000..fe9255f3 --- /dev/null +++ b/docs/donations.md @@ -0,0 +1,4 @@ +Donations +====== + +If you like Embark please consider donating to 0x8811FdF0F988f0CD1B7E9DE252ABfA5b18c1cDb1 diff --git a/docs/donations.rst b/docs/donations.rst new file mode 100644 index 00000000..d4daeb63 --- /dev/null +++ b/docs/donations.rst @@ -0,0 +1,5 @@ +Donations +========= + +If you like Embark please consider donating to +0x8811FdF0F988f0CD1B7E9DE252ABfA5b18c1cDb1 diff --git a/docs/embarkjs-communication.rst b/docs/embarkjs-communication.rst new file mode 100644 index 00000000..b0348b24 --- /dev/null +++ b/docs/embarkjs-communication.rst @@ -0,0 +1,46 @@ +EmbarkJS - Communication +======================== + +**initialization** + +For Whisper: + +.. code:: javascript + + EmbarkJS.Messages.setProvider('whisper') + +For Orbit: + +You'll need to use IPFS from master and run it as: +``ipfs daemon --enable-pubsub-experiment`` + +then set the provider: + +.. code:: javascript + + EmbarkJS.Messages.setProvider('orbit', {server: 'localhost', port: 5001}) + +**listening to messages** + +.. code:: javascript + + EmbarkJS.Messages.listenTo({topic: ["topic1", "topic2"]}).then(function(message) { console.log("received: " + message); }) + +**sending messages** + +you can send plain text + +.. code:: javascript + + EmbarkJS.Messages.sendMessage({topic: "sometopic", data: 'hello world'}) + +or an object + +.. code:: javascript + + EmbarkJS.Messages.sendMessage({topic: "sometopic", data: {msg: 'hello world'}}) + +note: array of topics are considered an AND. In Whisper you can use +another array for OR combinations of several topics e.g +``["topic1", ["topic2", "topic3"]]`` => +``topic1 AND (topic2 OR topic 3)`` diff --git a/docs/embarkjs-storage.rst b/docs/embarkjs-storage.rst new file mode 100644 index 00000000..c8a64585 --- /dev/null +++ b/docs/embarkjs-storage.rst @@ -0,0 +1,39 @@ +EmbarkJS - Storage +================== + +**initialization** + +The current available storage is IPFS. it can be initialized as + +.. code:: javascript + + EmbarkJS.Storage.setProvider('ipfs',{server: 'localhost', port: '5001'}) + +**Saving Text** + +.. code:: javascript + + EmbarkJS.Storage.saveText("hello world").then(function(hash) {}); + +**Retrieving Data/Text** + +.. code:: javascript + + EmbarkJS.Storage.get(hash).then(function(content) {}); + +**Uploading a file** + +.. code:: html + + + +.. code:: javascript + + var input = $("input[type=file"]); + EmbarkJS.Storage.uploadFile(input).then(function(hash) {}); + +**Generate URL to file** + +.. code:: javascript + + EmbarkJS.Storage.getUrl(hash); diff --git a/docs/embarkjs.rst b/docs/embarkjs.rst new file mode 100644 index 00000000..50c0e747 --- /dev/null +++ b/docs/embarkjs.rst @@ -0,0 +1,30 @@ +EmbarkJS +======== + +EmbarkJS is a javascript library meant to abstract and facilitate the +development of DApps. + +**promises** + +methods in EmbarkJS contracts will be converted to promises. + +.. code:: javascript + + var myContract = new EmbarkJS.Contract({abi: abiObject, address: "0x123"}); + myContract.get().then(function(value) { console.log("value is " + value.toNumber) }); + +**deployment** + +Client side deployment will be automatically available in Embark for +existing contracts: + +.. code:: javascript + + SimpleStorage.deploy().then(function(anotherSimpleStorage) {}); + +or it can be manually definied as + +.. code:: javascript + + var myContract = new EmbarkJS.Contract({abi: abiObject, code: code}); + myContract.deploy().then(function(anotherMyContractObject) {}); diff --git a/docs/index.rst b/docs/index.rst index 1ce3d9f0..1385fcf8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,9 +8,22 @@ Welcome to embark's documentation! .. toctree:: :maxdepth: 2 - :caption: Contents: - + installation.rst + usage.rst + dashboard.rst + creating-a-new-dapp.rst + libraries-and-languages-available.rst + using-contracts.rst + embarkjs.rst + embarkjs-storage.rst + embarkjs-communication.rst + tests.rst + working-with-different-chains.rst + structuring-application.rst + deploying-to-ipfs.rst + deploying-to-swarm.rst + donations.rst Indices and tables ================== diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..519d99e4 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,24 @@ +Installation +============ + +Requirements: geth (1.5.5 or higher), node (5.0.0) and npm Optional: +serpent (develop) if using contracts with Serpent, testrpc or ethersim +if using the simulator or the test functionality. Further: depending on +the dapp stack you choose: `IPFS `__ + +.. code:: bash + + $ npm -g install embark + + # If you plan to use the simulator instead of a real ethereum node. + $ npm -g install ethereumjs-testrpc + +See `Complete Installation +Instructions `__. + +**updating from embark 1** + +Embark's npm package has changed from ``embark-framework`` to +``embark``, this sometimes can create conflicts. To update first +uninstall embark-framework 1 to avoid any conflicts. +``npm uninstall -g embark-framework`` then ``npm install -g embark`` diff --git a/docs/libraries-and-languages-available.rst b/docs/libraries-and-languages-available.rst new file mode 100644 index 00000000..aac3f98b --- /dev/null +++ b/docs/libraries-and-languages-available.rst @@ -0,0 +1,14 @@ +Libraries and languages available +================================= + +Embark can build and deploy contracts coded in Solidity or Serpent. It +will make them available on the client side using EmbarkJS and Web3.js. + +Further documentation for these can be found below: + +- Smart Contracts: + `Solidity `__ and + `Serpent `__ +- Client Side: + `Web3.js `__ + and `EmbarkJS <#embarkjs>`__ diff --git a/docs/structuring-application.rst b/docs/structuring-application.rst new file mode 100644 index 00000000..bd56cac3 --- /dev/null +++ b/docs/structuring-application.rst @@ -0,0 +1,19 @@ +Structuring Application +======================= + +Embark is quite flexible and you can configure you're own directory +structure using ``embark.json`` + +.. code:: json + + # embark.json + { + "contracts": ["app/contracts/**"], + "app": { + "css/app.css": ["app/css/**"], + "js/app.js": ["embark.js", "app/js/**"], + "index.html": "app/index.html" + }, + "buildDir": "dist/", + "config": "config/" + } diff --git a/docs/tests.rst b/docs/tests.rst new file mode 100644 index 00000000..62c59780 --- /dev/null +++ b/docs/tests.rst @@ -0,0 +1,48 @@ +Tests +===== + +You can run specs with ``embark test``, it will run any test files under +``test/``. + +Embark includes a testing lib to fastly run & test your contracts in a +EVM. + +.. 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() { + before(function(done) { + var contractsConfig = { + "SimpleStorage": { + args: [100] + } + }; + EmbarkSpec.deployAll(contractsConfig, 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(); + }); + }); + }); + + }); + +Embark uses `Mocha `__ by default, but you can use +any testing framework you want. diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 00000000..63afbdfd --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,44 @@ +Usage +===== + +Usage - Demo +============ + +You can easily create a sample working DApp with the following: + +.. code:: bash + + $ embark demo + $ cd embark_demo + +You can run a REAL ethereum node for development purposes: + +.. code:: bash + + $ embark blockchain + +Alternatively, to use an ethereum rpc simulator simply run: + +.. code:: bash + + $ embark simulator + +By default embark blockchain will mine a minimum amount of ether and +will only mine when new transactions come in. This is quite usefull to +keep a low CPU. The option can be configured at +``config/blockchain.json``. Note that running a real node requires at +least 2GB of free ram, please take this into account if running it in a +VM. + +Then, in another command line: + +.. code:: bash + + $ embark run + +This will automatically deploy the contracts, update their JS bindings +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, +contracts included. There is no need to restart embark, refreshing the +page on the browser will do. diff --git a/docs/using-contracts.rst b/docs/using-contracts.rst new file mode 100644 index 00000000..7fc7a316 --- /dev/null +++ b/docs/using-contracts.rst @@ -0,0 +1,138 @@ +Using Contracts +=============== + +Embark will automatically take care of deployment for you and set all +needed JS bindings. For example, the contract below: + +.. code:: javascript + + # app/contracts/simple_storage.sol + contract SimpleStorage { + uint public storedData; + + function SimpleStorage(uint initialValue) { + storedData = initialValue; + } + + function set(uint x) { + storedData = x; + } + function get() constant returns (uint retVal) { + return storedData; + } + } + +Will automatically be available in Javascript as: + +.. code:: javascript + + # app/js/index.js + SimpleStorage.set(100); + SimpleStorage.get().then(function(value) { console.log(value.toNumber()) }); + SimpleStorage.storedData().then(function(value) { console.log(value.toNumber()) }); + +You can specify for each contract and environment its gas costs and +arguments: + +.. code:: json + + # config/contracts.json + { + "development": { + "gas": "auto", + "contracts": { + "SimpleStorage": { + "args": [ + 100 + ] + } + } + } + } + +If you are using multiple contracts, you can pass a reference to another +contract as ``$ContractName``, Embark will automatically replace this +with the correct address for the contract. + +.. code:: json + + # config/contracts.json + { + ... + "development": { + "contracts": { + "SimpleStorage": { + "args": [ + 100, + $MyStorage + ] + }, + "MyStorage": { + "args": [ + "initial string" + ] + }, + "MyMainContract": { + "args": [ + $SimpleStorage + ] + } + } + } + ... + } + +You can now deploy many instances of the same contract. e.g + +.. code:: json + + # config/contracts.json + { + "development": { + "contracts": { + "Currency": { + "deploy": false, + "args": [ + 100 + ] + }, + "Usd": { + "instanceOf": "Currency", + "args": [ + 200 + ] + }, + "MyCoin": { + "instanceOf": "Currency", + "args": [ + 200 + ] + } + } + } + } + ... + +Contracts addresses can be defined, If an address is defined the +contract wouldn't be deployed but its defined address will be used +instead. + +.. code:: json + + # config/contracts.json + { + ... + "development": { + "contracts": { + "UserStorage": { + "address": "0x123456" + }, + "UserManagement": { + "args": [ + "$UserStorage" + ] + } + } + } + ... + } diff --git a/docs/working-with-different-chains.rst b/docs/working-with-different-chains.rst new file mode 100644 index 00000000..1f845f4a --- /dev/null +++ b/docs/working-with-different-chains.rst @@ -0,0 +1,26 @@ +Working with different chains +============================= + +You can specify which environment to deploy to: + +``$ embark blockchain production`` + +``$ embark run production`` + +The environment is a specific blockchain configuration that can be +managed at config/blockchain.json + +.. code:: json + + # config/blockchain.json + ... + "livenet": { + "networkType": "livenet", + "rpcHost": "localhost", + "rpcPort": 8545, + "rpcCorsDomain": "http://localhost:8000", + "account": { + "password": "config/production/password" + } + }, + ... diff --git a/libraries-and-languages-available.md b/libraries-and-languages-available.md new file mode 100644 index 00000000..e69de29b