Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate docs via typedoc #522

Merged
merged 3 commits into from
May 27, 2019
Merged

Generate docs via typedoc #522

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
de4d574
Generate docs via typedoc
s1na May 24, 2019
984f30d
Update doc links
s1na May 27, 2019
820f3d2
Fix linting errors in developer.md
s1na May 27, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,11 @@ To build for standalone use in the browser, install `browserify` and check [run-

## VM

For documentation on `VM` instantiation, exposed API and emitted `events` see generated [API docs](./docs/index.md).
For documentation on `VM` instantiation, exposed API and emitted `events` see generated [API docs](./docs/README.md).

## StateManger

The API for the `StateManager` is currently in `Beta`, separate documentation can be found [here](./docs/stateManager.md), see also [release notes](https://github.com/ethereumjs/ethereumjs-vm/releases/tag/v2.5.0) from the `v2.5.0` VM release for details on the `StateManager` rewrite.
The API for the `StateManager` is currently in `Beta`, separate documentation can be found [here](./docs/classes/statemanager.md), see also [release notes](https://github.com/ethereumjs/ethereumjs-vm/releases/tag/v2.5.0) from the `v2.5.0` VM release for details on the `StateManager` rewrite.

# Internal Structure

Expand Down Expand Up @@ -98,7 +98,7 @@ The opFns for `CREATE`, `CALL`, and `CALLCODE` call back up to `runCall`.

# DEVELOPMENT

Developer documentation - currently mainly with information on testing and debugging - can be found [here](./docs/developer.md).
Developer documentation - currently mainly with information on testing and debugging - can be found [here](./developer.md).

# EthereumJS

Expand Down
38 changes: 19 additions & 19 deletions docs/developer.md → developer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

### Running Tests

Tests can be found in the ``tests`` directory, with ``FORK_CONFIG`` set in ``tests/tester.js``. There are test runners for [State tests](http://www.ethdocs.org/en/latest/contracts-and-transactions/ethereum-tests/state_tests/index.html) and [Blockchain tests](http://www.ethdocs.org/en/latest/contracts-and-transactions/ethereum-tests/blockchain_tests/index.html). VM tests are disabled since Frontier gas costs are not supported any more. Tests are then executed by the [ethereumjs-testing](https://github.com/ethereumjs/ethereumjs-testing) utility library using the official client-independent [Ethereum tests](https://github.com/ethereum/tests).
Tests can be found in the `tests` directory, with `FORK_CONFIG` set in `tests/tester.js`. There are test runners for [State tests](http://www.ethdocs.org/en/latest/contracts-and-transactions/ethereum-tests/state_tests/index.html) and [Blockchain tests](http://www.ethdocs.org/en/latest/contracts-and-transactions/ethereum-tests/blockchain_tests/index.html). VM tests are disabled since Frontier gas costs are not supported any more. Tests are then executed by the [ethereumjs-testing](https://github.com/ethereumjs/ethereumjs-testing) utility library using the official client-independent [Ethereum tests](https://github.com/ethereum/tests).

For a wider picture about how to use tests to implement EIPs you can have a look at this [reddit post](https://www.reddit.com/r/ethereum/comments/6kc5g3/ethereumjs_team_is_seeking_contributors/)
or the associated YouTube video introduction to [core development with Ethereumjs-vm](https://www.youtube.com/watch?v=L0BVDl6HZzk&feature=youtu.be).
Expand All @@ -19,8 +19,8 @@ Running the Blockchain tests:

`node ./tests/tester -b`

State tests and Blockchain tests can also be run against the ``dist`` folder (default: ``lib``):
State tests and Blockchain tests can also be run against the `dist` folder (default: `lib`):

`node ./tests/tester -b --dist`

State tests run significantly faster than Blockchain tests, so it is often a good choice to start fixing State tests.
Expand All @@ -39,13 +39,13 @@ Running a specific state test case:

`node ./tests/tester -s --test='stackOverflow'`

Only run test cases with selected ``data``, ``gas`` and/or ``value`` values (see
[attribute description](http://ethereum-tests.readthedocs.io/en/latest/test_types/state_tests.html) in
test docs), provided by the index of the array element in the test ``transaction`` section:
Only run test cases with selected `data`, `gas` and/or `value` values (see
[attribute description](http://ethereum-tests.readthedocs.io/en/latest/test_types/state_tests.html) in
test docs), provided by the index of the array element in the test `transaction` section:

`node tests/tester -s --test='CreateCollisionToEmpty' --data=0 --gas=1 --value=0`

Run a state test from a specified source file not under the ``tests`` directory:
Run a state test from a specified source file not under the `tests` directory:
`node ./tests/tester -s --customStateTest='{path_to_file}'`

#### Running tests with a reporter/formatter
Expand All @@ -67,51 +67,51 @@ The `-with` flag allows the specification of a formatter of your choosing:

#### Skipping Tests

There are three types of skip lists (``BROKEN``, ``PERMANENT`` and ``SLOW``) which
can be found in ``tests/tester.js``. By default tests from all skip lists are omitted.
There are three types of skip lists (`BROKEN`, `PERMANENT` and `SLOW`) which
can be found in `tests/tester.js`. By default tests from all skip lists are omitted.

You can change this behaviour with:

`node tests/tester -s --skip=BROKEN,PERMANENT`

to skip only the ``BROKEN`` and ``PERMANENT`` tests and include the ``SLOW`` tests.
There are also the keywords ``NONE`` or ``ALL`` for convenience.
to skip only the `BROKEN` and `PERMANENT` tests and include the `SLOW` tests.
There are also the keywords `NONE` or `ALL` for convenience.

It is also possible to only run the tests from the skip lists:

`node tests/tester -s --runSkipped=SLOW`

### CI Test Integration

Tests are run on ``CircleCI`` on every PR, configuration can be found in ``.circleci/config.yml``.
Tests are run on `CircleCI` on every PR, configuration can be found in `.circleci/config.yml`.

### Debugging

#### Local Debugging

For state tests you can use the ``--jsontrace`` flag to output opcode trace information.
For state tests you can use the `--jsontrace` flag to output opcode trace information.

Blockchain tests support `--debug` to verify the postState:

`node ./tests/tester -b --debug --test='ZeroValue_SELFDESTRUCT_ToOneStorageKey_OOGRevert_d0g0v0_EIP158'`
`node ./tests/tester -b --debug --test='ZeroValue_SELFDESTRUCT_ToOneStorageKey_OOGRevert_d0g0v0_EIP158'`

All/most State tests are replicated as Blockchain tests in a ``GeneralStateTests`` [sub directory](https://github.com/ethereum/tests/tree/develop/BlockchainTests/GeneralStateTests) in the Ethereum tests repo, so for debugging single test cases the Blockchain test version of the State test can be used.
All/most State tests are replicated as Blockchain tests in a `GeneralStateTests` [sub directory](https://github.com/ethereum/tests/tree/develop/BlockchainTests/GeneralStateTests) in the Ethereum tests repo, so for debugging single test cases the Blockchain test version of the State test can be used.

#### Comparing Stack Traces

Other client implementations often also provide functionality for output trace information.

A convenient way is to use a local ``geth`` installation (can be the binary installation and doesn't has to be build from source or something) and then use the included ``evm`` tool like:
A convenient way is to use a local `geth` installation (can be the binary installation and doesn't has to be build from source or something) and then use the included `evm` tool like:

```shell
evm --json --nomemory statetest node_modules/ethereumjs-testing/tests/GeneralStateTests/stCreate2/create2collisionCode2.json
```

If you want to have only the output for a specific fork you can go into the referenced json test file and temporarily delete the ``post`` section for the non-desired fork outputs (or, more safe and also more convenient on triggering later: copy the test files you are interested in to your working directory and then modify without further worrying).
If you want to have only the output for a specific fork you can go into the referenced json test file and temporarily delete the `post` section for the non-desired fork outputs (or, more safe and also more convenient on triggering later: copy the test files you are interested in to your working directory and then modify without further worrying).

#### Debugging Tools

For comparing ``EVM`` traces [here](https://gist.github.com/cdetrio/41172f374ae32047a6c9e97fa9d09ad0) are some instructions for setting up ``pyethereum`` to generate corresponding traces for state tests.
For comparing `EVM` traces [here](https://gist.github.com/cdetrio/41172f374ae32047a6c9e97fa9d09ad0) are some instructions for setting up `pyethereum` to generate corresponding traces for state tests.

Compare TAP output from blockchain/state tests and produces concise diff of the differences between them (example):

Expand All @@ -121,7 +121,7 @@ curl https://gist.githubusercontent.com/jwasinger/e7004e82426ff0a7137a88d273f118
python utils/diffTestOutput.py output-wip-byzantium.txt output-master.txt
```

An extremely rich and powerful toolbox is the [evmlab](https://github.com/holiman/evmlab) from ``holiman``, both for debugging and creating new test cases or example data.
An extremely rich and powerful toolbox is the [evmlab](https://github.com/holiman/evmlab) from `holiman`, both for debugging and creating new test cases or example data.

## Profiling

Expand Down
35 changes: 35 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@

# ethereumjs-vm

## Index

### Enumerations

* [ERROR](enums/error.md)

### Classes

* [StateManager](classes/statemanager.md)
* [VM](classes/vm.md)
* [VmError](classes/vmerror.md)

### Interfaces

* [ExecResult](interfaces/execresult.md)
* [InterpreterResult](interfaces/interpreterresult.md)
* [RunBlockCb](interfaces/runblockcb.md)
* [RunBlockOpts](interfaces/runblockopts.md)
* [RunBlockResult](interfaces/runblockresult.md)
* [RunCallCb](interfaces/runcallcb.md)
* [RunCallOpts](interfaces/runcallopts.md)
* [RunCodeCb](interfaces/runcodecb.md)
* [RunCodeOpts](interfaces/runcodeopts.md)
* [RunTxCb](interfaces/runtxcb.md)
* [RunTxOpts](interfaces/runtxopts.md)
* [RunTxResult](interfaces/runtxresult.md)
* [StorageDump](interfaces/storagedump.md)
* [TxReceipt](interfaces/txreceipt.md)
* [VMOpts](interfaces/vmopts.md)

---

Loading