diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 3e6108d4e..000000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = embark -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 7bb0e679f..000000000 --- a/docs/conf.py +++ /dev/null @@ -1,160 +0,0 @@ -# -*- coding: utf-8 -*- -# -# ENS documentation build configuration file, created by -# sphinx-quickstart on Thu Dec 15 16:45:41 2016. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -from recommonmark.parser import CommonMarkParser - -source_parsers = { - '.md': CommonMarkParser, -} - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.mathjax'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -source_suffix = ['.rst', '.md'] - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Embark' -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 -# built documents. -# -# The short X.Y version. -version = u'2.5' -# The full version, including alpha/beta/rc tags. -release = u'2.5.2' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'Embarkdoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'Embark.tex', u'Embark Documentation', - u'Iuri Matias \\textless{}\\textgreater{}', 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'embark', u'Embark Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'Embark', u'Embark Documentation', - author, 'Embark', 'One line description of project.', - 'Miscellaneous'), -] - - - diff --git a/docs/configuring-communication.rst b/docs/configuring-communication.rst deleted file mode 100644 index 38bc909e7..000000000 --- a/docs/configuring-communication.rst +++ /dev/null @@ -1,22 +0,0 @@ -Configuring Communication (Whisper, Orbit) -========================== - -Embark will check your prefered communication configuration in the file ``config/communication.json``. This file will contain the prefered configuration for each environment. With ``default`` being the configuration fields that applies to every environment. Each of those can be individually overriden in a per environment basis. - -e.g : - -.. code:: javascript - - { - "default": { - "enabled": true, - "provider": "whisper", - "available_providers": ["whisper", "orbit"] - } - } - -options available: - * ``enabled`` (boolean: true/false) to enable or completly disable communication support - * ``provider`` (string: "wisper" or "orbit") desired provider to automatically connect to on the dapp. e.g in the example above, seting this to ``"whisper"`` will automaticaly add ``EmbarkJS.setProvider('whisper')`` to the generated code - * ``available_providers`` (array: ["whisper", "orbit"]) list of communication platforms to be supported on the dapp. This will affect what's available with the EmbarkJS library on the dapp so if you don't need Orbit for e.g, removing it from this will considerably reduce the file size of the generated JS code. - diff --git a/docs/configuring-storage.rst b/docs/configuring-storage.rst deleted file mode 100644 index 0a6267752..000000000 --- a/docs/configuring-storage.rst +++ /dev/null @@ -1,37 +0,0 @@ -Configuring Storage (IPFS) -========================== - -Embark will check your prefered storage configuration in the file ``config/storage.json``. This file will contain the prefered configuration for each environment. With ``default`` being the configuration fields that applies to every environment. Each of those can be individually overriden in a per environment basis. - -e.g : - -.. code:: javascript - - { - "default": { - "enabled": true, - "ipfs_bin": "ipfs", - "provider": "ipfs", - "available_providers": ["ipfs"], - "host": "localhost", - "port": 5001, - "versions": { - "ipfs-api": "17.2.4" - } - }, - "development": { - "enabled": true, - "provider": "ipfs", - "host": "localhost", - "port": 5001 - } - } - -options available: - * ``enabled`` (boolean: true/false) to enable or completly disable storage support - * ``ipfs_bin`` (string) name or desired path to the ipfs binary - * ``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. - * ``host`` and ``port`` of the ipfs node to connect to. - * ``versions`` (object) key-value hash of library and its desired version - diff --git a/docs/creating-a-new-dapp.rst b/docs/creating-a-new-dapp.rst deleted file mode 100644 index 66d9435b7..000000000 --- a/docs/creating-a-new-dapp.rst +++ /dev/null @@ -1,43 +0,0 @@ -Creating a new DApp -=================== - -If you want to create a blank new app. - -.. code:: bash - - $ embark new AppName - $ cd AppName - -To run Embark then in one console run: - -.. code:: bash - - $ embark blockchain - -And in another console run: - -.. code:: bash - - $ embark run - -DApp Structure -============== - -.. code:: bash - - app/ # dapp code - contracts/ #smart contracts - config/ - |___ blockchain.json #rpc and blockchain configuration - |___ contracts.json #ethereum contracts configuration - |___ storage.json #ipfs configuration - |___ communication.json #whisper/orbit configuration - |___ webserver.json #dev webserver configuration - test/ - |___ #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 - diff --git a/docs/dashboard.rst b/docs/dashboard.rst deleted file mode 100644 index 6f77d98ff..000000000 --- a/docs/dashboard.rst +++ /dev/null @@ -1,46 +0,0 @@ -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. - -**without the dashboard** - -if you prefer to only see the logs, you can disable the dashboard with the -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 - diff --git a/docs/deploying-to-ipfs.rst b/docs/deploying-to-ipfs.rst deleted file mode 100644 index a0c4d7bcf..000000000 --- a/docs/deploying-to-ipfs.rst +++ /dev/null @@ -1,9 +0,0 @@ -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 -``livenet`` environment then you can deploy to that chain by -specifying the environment ``embark ipfs livenet``. - diff --git a/docs/deploying-to-swarm.rst b/docs/deploying-to-swarm.rst deleted file mode 100644 index aca155d03..000000000 --- a/docs/deploying-to-swarm.rst +++ /dev/null @@ -1,4 +0,0 @@ -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 deleted file mode 100644 index 77843e331..000000000 --- a/docs/donations.md +++ /dev/null @@ -1,4 +0,0 @@ -Donations -====== - -If you like Embark please consider donating to 0xFA239D14c7117C3D2370B2a4c4238534391fadd9 diff --git a/docs/donations.rst b/docs/donations.rst deleted file mode 100644 index e8ebe277c..000000000 --- a/docs/donations.rst +++ /dev/null @@ -1,4 +0,0 @@ -Donations -========= - -If you like Embark please consider donating to 0xFA239D14c7117C3D2370B2a4c4238534391fadd9 diff --git a/docs/embarkjs-communication.rst b/docs/embarkjs-communication.rst deleted file mode 100644 index 7e28292ba..000000000 --- a/docs/embarkjs-communication.rst +++ /dev/null @@ -1,46 +0,0 @@ -EmbarkJS - Communication (Whisper, Orbit) -========================================= - -**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 deleted file mode 100644 index 360b65e0a..000000000 --- a/docs/embarkjs-storage.rst +++ /dev/null @@ -1,62 +0,0 @@ -EmbarkJS - Storage (IPFS) -========================= - -**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) {}) - .catch(function(err) { - if(err){ - console.log("IPFS saveText Error => " + err.message); - } - }); - -**Retrieving Data/Text** - -.. code:: javascript - - EmbarkJS.Storage.get(hash) - .then(function(content) {}) - .catch(function(err) { - if(err){ - console.log("IPFS get Error => " + err.message); - } - }); - -**Uploading a file** - -.. code:: html - - - -.. code:: javascript - - var input = $("input[type=file"]); - EmbarkJS.Storage.uploadFile(input) - .then(function(hash) {}) - .catch(function(err) { - if(err){ - console.log("IPFS uploadFile Error => " + err.message); - } - }); - -**Generate URL to file** - -.. code:: javascript - - 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"]``` - diff --git a/docs/embarkjs.rst b/docs/embarkjs.rst deleted file mode 100644 index a3bb17549..000000000 --- a/docs/embarkjs.rst +++ /dev/null @@ -1,36 +0,0 @@ -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([args], {options}).then(function(anotherSimpleStorage) {}); - -or it can be manually definied as - -.. code:: javascript - - var myContract = new EmbarkJS.Contract({abi: abiObject, code: code}); - myContract.deploy([args], {options}).then(function(anotherMyContractObject) {}); - -so you can define your gas as - -.. code:: javascript - - myContract.deploy([100, "seconde argument"], {gas: 800000}).then(function(anotherMyContractObject) {}); diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 24b444c8a..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. embark documentation master file, created by - sphinx-quickstart on Tue Jan 10 06:39:27 2017. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to embark's documentation! -================================== - -This is a work in progress, feel free to contribute! - -.. toctree:: - :maxdepth: 2 - - installation.rst - usage.rst - dashboard.rst - creating-a-new-dapp.rst - libraries-and-languages-available.rst - using-contracts.rst - configuring-storage.rst - configuring-communication.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 - plugins.rst - using-embark-with-grunt.rst - other.rst - donations.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index c2b7c23bd..000000000 --- a/docs/installation.rst +++ /dev/null @@ -1,24 +0,0 @@ -Installation -============ - -Requirements: geth (1.6.5 or higher recommended), node (6.9.1 or higher is recommended) and npm -serpent (develop) if using contracts with Serpent, testrpc (3.0 or higher) -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 deleted file mode 100644 index aac3f98be..000000000 --- a/docs/libraries-and-languages-available.rst +++ /dev/null @@ -1,14 +0,0 @@ -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/make.bat b/docs/make.bat deleted file mode 100644 index 5fb029303..000000000 --- a/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build -set SPHINXPROJ=embark - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/other.rst b/docs/other.rst deleted file mode 100644 index 243c820dd..000000000 --- a/docs/other.rst +++ /dev/null @@ -1,8 +0,0 @@ -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``` - - - diff --git a/docs/plugins.rst b/docs/plugins.rst deleted file mode 100644 index ca7827eba..000000000 --- a/docs/plugins.rst +++ /dev/null @@ -1,404 +0,0 @@ -Extending functionality with plugins -==================================== - -**To add a plugin to embark:** - -1. Add the npm package to package.json - e.g ``npm install embark-babel --save`` -2. Then add the package to ``plugins:`` in embark.json - e.g ``"plugins": { "embark-babel": {} }`` - -**Creating a plugin:** - -1. ``mkdir yourpluginname`` -2. ``cd yourpluginname`` -3. ``npm init`` -4. create and edit ``index.js`` -5. add the following code: - -.. code:: javascript - - module.exports = function(embark) { - } - -The ``embark`` object then provides an api to extend different functionality of embark. - -**Usecases examples** - -* 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 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``, ``embark.registerImportFile``) -* 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 create a different contract wrapper (``embark.registerContractsGeneration``) -* plugin to add new console commands (``embark.registerConsoleCommand``) -* 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 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** - -Object containing the config for the plugin specified in embark.json, for e.g with: - -.. code:: json - - "plugins": { - "embark-babel": { "files": ["**/*.js", "!**/jquery.min.js"], "presets": ["es2015", "react"] } - } - -``embark.pluginConfig`` will contain ``{ "files": ["**/*.js", "!**/jquery.min.js"], "presets": ["es2015", "react"] }`` - -**embark.registerPipeline(matchingFiles, callback(options))** - -This call will return the content of the current asset file so the plugin can transform it in some way. Typically this is used to implement pipeline plugins such as Babel, JSX, sass to css, etc.. - -``matchingFiles`` is an array of matching files the plugin should be called for e.g [``**/*.js``, ``!vendor/jquery.js``] matches all javascript files except vendor/jquery.js - -options available: - * targetFile - filename to be generated - * source - content of the file - -expected return: ``string`` - -.. code:: javascript - - var babel = require("babel-core"); - require("babel-preset-react"); - - module.exports = function(embark) { - embark.registerPipeline(["**/*.js", "**/*.jsx"], function(options) { - return babel.transform(options.source, {minified: true, presets: ['react']}).code; - }); - } - -**embark.registerContractConfiguration(contractsConfig)** - -This call is used to specify a configure of one or more contracts in one or -several environments. This is useful for specifying the different configurations -a contract might have depending on the enviroment. For instance in the code -bellow, the ``DGDToken`` contract code will redeployed with the arguments -``100`` in any environment, except for the livenet since it's already deployed -there at a particular address. - -Typically this call is used in combination with ``embark.addContractFile`` - -``contractsConfig`` is an object in the same structure as the one found in the -contracts configuration at ``config/contracts.json``. The users own -configuration will be merged with the one specified in the plugins. - -.. code:: javascript - - module.exports = function(embark) { - embark.registerContractConfiguration({ - "default": { - "contracts": { - "DGDToken": { - "args": [ - 100 - ] - } - } - }, - "livenet": { - "contracts": { - "DGDToken": { - "address": "0xe0b7927c4af23765cb51314a0e0521a9645f0e2a" - } - } - } - }); - } - -**embark.addContractFile(file)** - -Typically this call is used in combination with ``embark.registerContractConfiguration``. If you want to make the contract available but not automatically deployed without the user specifying so you can use ``registerContractConfiguration`` to set the contract config to ``deploy: false``, this is particularly useful for when the user is meant to extend the contract being given (e.g ``contract MyToken is StandardToken``) - -``file`` is the contract file to add to embark, the path should relative to the plugin. - -.. code:: javascript - - module.exports = function(embark) { - embark.addContractFile("./DGDToken.sol"); - } - -**embark.addFileToPipeline(file, options)** - -This call is used to add a file to the pipeline so it's included with the dapp on the client side. - -``file`` is the file to add to the pipeline, the path should relative to the plugin. - -``options`` available: - * skipPipeline - If true it will not apply transformations to the file. For - example if you have a babel plugin to transform es6 code or a minifier plugin, setting this to - true will not apply the plugin on this file. - -.. code:: javascript - - module.exports = function(embark) { - embark.addFileToPipeline("./jquery.js", {skipPipeline: true}); - } - -**embark.registerBeforeDeploy(callback(options))** - -This call can be used to add handler to process contract code after it was generated, but immediately before it is going to be deployed. -It is useful to replace placeholders with dynamic values. - -options available: - * embarkDeploy - instance of Deploy class. Has following fields: web3, contractsManager, logger, env, chainConfig, gasLimit. - * pluginConfig - plugin configuration object from embark.json - * deploymentAccount - address of account which will be used to deploy this contract - * contract - contract object. - * callback - callback function that handler must call with result object as the only argument. Result object must have field contractCode with (un)modified code from contract.code - -expected return: ignored - -example: - -.. code:: javascript - - module.exports = function(embark) { - embark.registerBeforeDeploy(function(options) { - var code = options.contract.code.replace(/deaddeaddeaddeaddeaddeaddeaddeaddeaddead/ig, 'c0dec0dec0dec0dec0dec0dec0dec0dec0dec0de'); - options.callback({ contractCode: code }); - return; // ignored - }); - } - - -**embark.registerClientWeb3Provider(callback(options))** - -This call can be used to override the default web3 object generation in the dapp. it's useful if you want to add a plugin to interact with services like http://infura.io or if you want to use your own web3.js library extension. - -options available: - * rpcHost - configured rpc Host to connect to - * rpcPort - configured rpc Port to connect to - * blockchainConfig - object containing the full blockchain configuration for the current environment - -expected return: ``string`` - -example: - -.. code:: javascript - - module.exports = function(embark) { - embark.registerClientWeb3Provider(function(options) { - return "web3 = new Web3(new Web3.providers.HttpProvider('http://" + options.rpcHost + ":" + options.rpcPort + "');"; - }); - } - - -**embark.registerContractsGeneration(callback(options))** - -By default Embark will use EmbarkJS to declare contracts in the dapp. You can override and use your own client side library. - -options available: - * contracts - Hash of objects containing all the deployed contracts. (key: contractName, value: contract object) - * abiDefinition - * code - * deployedAddress - * gasEstimates - * gas - * gasPrice - * runtimeByteCode - -expected return: ``string`` - -.. code:: javascript - - module.exports = function(embark) { - embark.registerContractsGeneration(function(options) { - for(var className in this.contractsManager.contracts) { - var abi = JSON.stringify(contract.abiDefinition); - - return className + " = " + web3.eth.contract(" + abi + ").at('" + contract.deployedAddress + "');"; - } - }); - } - -**embark.registerConsoleCommand(callback(options))** - -This call is used to extend the console with custom commands. - -expected return: ``string`` (output to print in console) or ``boolean`` (skip command if false) - -.. code:: javascript - - module.exports = function(embark) { - embark.registerConsoleCommand(function(cmd, options) { - if (cmd === "hello") { - return "hello there!"; - } - // continue to embark or next plugin; - return false; - }); - } - -**embark.registerCompiler(extension, callback(contractFiles, doneCallback))** - -expected doneCallback arguments: ``err`` and ``hash`` of compiled contracts - - * Hash of objects containing the compiled contracts. (key: contractName, value: contract object) - * code - contract bytecode (string) - * runtimeBytecode - contract runtimeBytecode (string) - * gasEstimates - gas estimates for constructor and methods (hash) - * e.g ``{"creation":[20131,38200],"external":{"get()":269,"set(uint256)":20163,"storedData()":224},"internal":{}}`` - * functionHashes - object with methods and their corresponding hash identifier (hash) - * e.g ``{"get()":"6d4ce63c","set(uint256)":"60fe47b1","storedData()":"2a1afcd9"}`` - * abiDefinition - contract abi (array of objects) - * e.g ``[{"constant":true,"inputs":[],"name":"storedData","outputs":[{"name":"","type":"uint256"}],"payable":false,"type":"function"}, etc...`` - -below a possible implementation of a solcjs plugin: - -.. code:: javascript - - var solc = require('solc'); - - module.exports = function(embark) { - embark.registerCompiler(".sol", function(contractFiles, cb) { - // prepare input for solc - var input = {}; - for (var i = 0; i < contractFiles.length; i++) { - var filename = contractFiles[i].filename.replace('app/contracts/',''); - input[filename] = contractFiles[i].content.toString(); - } - - // compile files - var output = solc.compile({sources: input}, 1); - - // generate the compileObject expected by embark - var json = output.contracts; - var compiled_object = {}; - for (var className in json) { - var contract = json[className]; - - compiled_object[className] = {}; - compiled_object[className].code = contract.bytecode; - compiled_object[className].runtimeBytecode = contract.runtimeBytecode; - compiled_object[className].gasEstimates = contract.gasEstimates; - compiled_object[className].functionHashes = contract.functionHashes; - compiled_object[className].abiDefinition = JSON.parse(contract.interface); - } - - cb(null, compiled_object); - }); - } - -**embark.logger** - -To print messages to the embark log is it better to use ``embark.logger`` -instead of ``console``. - -e.g ``embark.logger.info("hello")`` - -**embark.events.on(eventName, callback(*args))** - -This call is used to listen and react to events that happen in Embark such as contract deployment - -* eventName - name of event to listen to - * available events: - * "contractsDeployed" - triggered when contracts have been deployed - * "file-add", "file-change", "file-remove", "file-event" - triggered on a file change, args is (filetype, path) - * "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 - * "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 - - module.exports = function(embark) { - embark.events.on("contractsDeployed", function() { - embark.logger.info("plugin says: your contracts have been deployed"); - }); - embark.events.on("file-changed", function(filetype, path) { - if (type === 'contract') { - embark.logger.info("plugin says: you just changed the contract at " + path); - } - }); - } - -**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")); - } - diff --git a/docs/structuring-application.rst b/docs/structuring-application.rst deleted file mode 100644 index c384a9fb8..000000000 --- a/docs/structuring-application.rst +++ /dev/null @@ -1,22 +0,0 @@ -Structuring Application -======================= - -Embark is quite flexible and you can configure you're own directory -structure using ``embark.json`` - -.. code:: json - - # embark.json - { - "contracts": ["contracts/**"], - "app": { - "js/app.js": ["app/dapp.js"], - "index.html": "app/index.html", - "css/app.css": ["app/css/**"], - "images/": ["app/images/**"] - }, - "buildDir": "dist/", - "config": "config/", - "plugins": {} - } - diff --git a/docs/tests.rst b/docs/tests.rst deleted file mode 100644 index 08dac4db5..000000000 --- a/docs/tests.rst +++ /dev/null @@ -1,167 +0,0 @@ -Testing Ethereum Contracts -========================== - -You can run specs with ``embark test``, it will run all the test files under -``test/``. You can run a specific test file with ``embark test - -Embark includes a testing lib to fastly run & test your contracts in a -EVM. - -.. code:: javascript - - # test/simple_storage_spec.js - 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(); - }); - }); - }); - - }); - -**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 `__ by default, but you can use -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`` - -**accessing accounts** - -The callback used in the function ``deployAll`` will let you access the accounts configured in the EVM. -You can assign them to a variable and use them in your tests. - -.. code:: javascript - - var accountArr; - EmbarkSpec.deployAll(contractsConfig, (accounts) => { - accountArr = accounts; - done(); - }); - -**creating contract instances in your tests** - -Embark handles the deployment of your contracts through the function ``deployAll``. -However you can use ``web3.eth.contract`` for creating instances of your contracts manually. - -.. code:: javascript - - var simpleStorageJson = require('../dist/contracts/SimpleStorage.json'); - var accountArr; - var simpleStorage; - - describe("SimpleStorage", function() { - this.timeout(0); - before(function(done) { - EmbarkSpec.deployAll({}, (accounts) => { - accountArr = accounts; - done(); - }); - }); - - it("should deploy a contract instance", function(done) { - var simpleStorageContract = new web3.eth.Contract(simpleStorageJson.abi); - simpleStorageContract.deploy({data: simpleStorageJson.code, arguments: [100]}) - .send({from: accountArr[0], gas: 5000000, gasPrice: 1}) - .then(function(contractInstance){ - simpleStorage = contractInstance; - simpleStorage.setProvider(web3.currentProvider); - assert(simpleStorage.options.address != null); - }) - .finally(done); - }); - }); diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index bbef4c947..000000000 --- a/docs/usage.rst +++ /dev/null @@ -1,77 +0,0 @@ -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. - -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) - diff --git a/docs/using-contracts.rst b/docs/using-contracts.rst deleted file mode 100644 index 3f5e6ac32..000000000 --- a/docs/using-contracts.rst +++ /dev/null @@ -1,200 +0,0 @@ -Configuring & 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 - import SimpleStorage from 'Embark/contracts/SimpleStorage'; - - 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 -arguments: - -.. code:: json - - # config/contracts.json - { - "development": { - "gas": "auto", - "contracts": { - "SimpleStorage": { - "args": [ - 100 - ], - "gas": 800000, - "gasPrice": 5 - } - } - } - } - -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. -You can also specify interfaces and choose to not deploy contracts (for e.g in case they are interfaces) - -.. code:: json - - # config/contracts.json - { - ... - "development": { - "contracts": { - "SimpleStorage": { - "args": [ - 100, - "$MyStorage" - ] - }, - "MyStorage": { - "args": [ - "initial string" - ] - }, - "MyMainContract": { - "args": [ - "$SimpleStorage" - ] - }, - "MyContractInteface": { - "deploy": false - } - } - } - ... - } - -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 - ] - } - } - } - } - ... - -Account from which you want to deploy a contract can be specified using "from" or "fromIndex" parameters. - -| "from" - should be account address string. -| "fromIndex" - should be index in accounts array as retrieved by web3.eth.getAccounts() . - -If both "from" and "fromIndex" are specified, the "from" will be used. - -Example: - - .. code:: json - - # config/contracts.json - { - "development": { - "contracts": { - "Currency": { - "deploy": true, - "from": '0xfeedaa0e295b09cd84d6ea2cce390eb443bcfdfc', - "args": [ - 100 - ] - }, - "MyStorage": { - "fromIndex": 0, - "args": [ - "initial string" - ] - }, - } - } - } - ... - -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" - ] - } - } - } - ... - } - -You can specify actions to do after the deployment of a contract using the "onDeploy" parameter. - -| "onDeploy" - should be an array of javascript instructions that will be evaluated and executed - -.. code:: json - - # config/contracts.json - { - "development": { - "gas": "auto", - "contracts": { - "SimpleStorage": { - "args": [ - 100 - ], - "onDeploy": ["SimpleStorage.methods.set(150).send()"] - } - } - } - } \ No newline at end of file diff --git a/docs/using-embark-with-grunt.rst b/docs/using-embark-with-grunt.rst deleted file mode 100644 index a71fc1067..000000000 --- a/docs/using-embark-with-grunt.rst +++ /dev/null @@ -1,34 +0,0 @@ -Using Embark with Grunt -==================================== - -**1. Edit embark.json** - -Edit ``embark.json`` to have the line ``"js/app.js": ["embark.js"]``, this will make embark create the file containing the contracts initilization to ``dist/app.js``. - -.. code:: json - - { - "contracts": ["app/contracts/**"], - "app": { - "app.js": ["embark.js"] - }, - "buildDir": "dist/", - "config": "config/", - "plugins": { - } - } - -**2. add the generated file to Grunt config file so it's included with the other assets** - -.. code:: coffee - - module.exports = (grunt) -> - - grunt.initConfig( - files: - js: - src: [ - "dist/app.js" - "app/js/**/*.js" - ] - diff --git a/docs/working-with-different-chains.rst b/docs/working-with-different-chains.rst deleted file mode 100644 index de4fd3fbb..000000000 --- a/docs/working-with-different-chains.rst +++ /dev/null @@ -1,72 +0,0 @@ -Working with different chains -============================= - -You can specify which environment to deploy to: - -``$ embark blockchain livenet`` - -``$ embark run livenet`` - -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/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": { - "password": "config/livenet/password" - } - }, - ... - - # config/development/genesis.json - { - "config": { - "homesteadBlock": 0, - "byzantiumBlock": 0, - "daoForkSupport": true - }, - "nonce": "0x0000000000000042", - "difficulty": "0x0", - "alloc": { - "0x3333333333333333333333333333333333333333": {"balance": "15000000000000000000"} - }, - "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "coinbase": "0x3333333333333333333333333333333333333333", - "timestamp": "0x00", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "extraData": "0x", - "gasLimit": "0x7a1200" - } -