- Use Node.js v16.0.0.
- Why v16.0.0? Because this is the first LTS release of Node.js v16 and is the earliest version Ganache supports.
- recommendation: use nvm on Linux and macOS, and nvm-windows on
Windows, to configure your node version.
- On Linux and macOS, if you have
nvm
installed, just runnvm use
to switch to Node.js v16.0.0.
- On Linux and macOS, if you have
git clone git@github.com:trufflesuite/ganache.git
cd ganache
npm install
(use npm v7)
If installation fails due to a node-gyp
issue you may need to perform some additional system configuration.
note: Ganache uses node-gyp v7.1.2 as part of its build system, which requires Python v2.7, v3.5, v3.6, v3.7, or v3.8 to be installed on the system.
- Install https://www.npmjs.com/package/windows-build-tools
npm install --global windows-build-tools
- Make sure
npm
commands are not run asroot
. - If you get an error that
make
isn't installed you might need to also install thebuild-essential
package - example
sudo apt update && sudo apt install build-essential
- Determine whether you have a compatible version of Python installed:
- example:
python --version
(andpython3 --version
ifpython3
is installed)
- example:
- If you do not have a compatible version installed: (v2.7, v3.5, v3.6, v3.7, or v3.8), you will need to install it:
- example:
sudo apt update && sudo apt install python2.7
- example:
- You may need to configure the python dependency (see node-gyp for details on different ways to do this):
- example:
npm config set python <path-to-python-executable>
- example:
- Attempt to install Xcode command line tools (the console will tell you if they're already installed)
- example:
xcode-select --install
- example:
- Determine whether you have a compatible version of Python installed:
- example:
python --version
(andpython3 --version
ifpython3
is installed)
- example:
- If you do not have a compatible version installed: (v2.7, v3.5, v3.6, v3.7, or v3.8), you will need to install it: (we recommend pyenv to manage your python installation)
- Install
pyenv
- Setup your shell environment for
pyenv
- Install Python:
pyenv install 2.7
- You may need to configure the python dependency (see node-gyp for details on different ways to do this):
- example:
npm config set python <path-to-python-executable>
- Install
- If the above steps don't fix the
node-gyp
issue and you've recently updated your OS, you may need to re-install Xcode command line tools:- Remove the existing, broken installation:
rm -rf /Library/Developer/CommandLineTools
- Install them again:
xcode-select --install
- Remove the existing, broken installation:
npm run reinstall
Which just runs these commands for you:
npm run clean
npm install
This deletes all node_modules
folders, as well as all generated lib
directories, then reinstalls all modules.
Compiles the ganache
package and its internal dependencies and subdependencies:
npm run tsc
To compile a package directly:
npx lerna run --scope @ganache/<name> tsc
This can be useful if the package isn't yet in ganache's dependency tree.
Creates the bundle that can be published to npm
npm run build
Runs all tests:
npm test
(or the shorthand,npm t
)
To start the cli run:
npm start
To pass options to the cli you must separate the args with --
, e.g.:
npm start -- --chain.chainId 1 --wallet.totalAccounts 5
npm run create <name> --location <location> [--folder <folder>]
This will create a new package with Ganache defaults at <location>/<name>
.
If you provide the optional --folder
option, the package will be created at <location>/<folder>
.
npx lerna add <module>[@version] -E [--dev] [--peer] --scope=<package>
Where <module>
is the npm-module you want to add and <package>
is where you want to add it. See
@lerna/add documentation for more details.
Example:
npx lerna add @ganache/options -E --scope=@ganache/ethereum
will add our local @ganache/options
package to the @ganache/ethereum
package.
cd
to the package and then run npm uninstall <module>
- Enable "Developer Mode" by going to Settings -> Developer Settings -> Then select Developer Mode.
- Copy the
launch.json
file into a folder named.vscode
in root of the project. - Set breakpoints by clicking the margin to the left of the line numbers (you can set conditional breakpoints or logpoints by right-clicking instead)
- Press F5 (or select
Run
🡺Start Debugging
from the menu bar) to automatically start debugging.
To change which files are debugged update your .vscode/launch.json
file glob to match your target files. Here is an
example to debug only test files in the @ganache/ethereum
package:
diff --git a/.vscode/launch.json b/.vscode/launch.json
index 2a2aa9e..57cbf21 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -24,7 +24,7 @@
"--colors",
"--require",
"ts-node/register",
- "${workspaceFolder}/packages/**/tests/**/*.test.ts"
+ "${workspaceFolder}/packages/ethereum/ethereum/tests/**/*.test.ts"
],
"skipFiles": ["<node_internals>/**"],
"console": "integratedTerminal",
These are guidelines, not rules. :-)
- Use Node.js v16.0.0 for most local development.
- Use
bigint
literals, e.g.,123n
; if the number is externally configurable and/or could exceedNumber.MAX_SAFE_INTEGER
. - Write tests.
- Do not use "Optional Chaining" (
obj?.prop
). I'd love to enable this, but TypeScript makes it hard to use bigint literals and optional chaining together. If you figure it out, delete this rule! - Prefer using a single loop to functional chaining.
- Prefer performant code over your own developer experience.
- Document complex code. Explain why the code does what it does.
- Feel free to be clever, just document why you're being clever. If it's hard to read, comment what the code does, too.
- Add JSDoc comments to public class members where it makes sense.
- Before adding an external dependency check its code for quality, its # of external dependencies, its node version support, and make sure it's absolutely necessary.
- Pin all dependencies, even dev dependencies.
- Use npm; do not use yarn.
- Don't use web3, ethers, etc in ganache core code. (Tests are fine)
- Ensure a smooth development experience on Windows, Mac, and Linux.
- Do not use bash scripts for critical development or configuration.
- Do not use CLI commands in npm scripts or build scripts that aren't available by default on supported platforms.
- Push your code often (at least every-other day!), even broken WIP code (to your own branch, of course).
This section is mostly for the maintainers of Ganache, not individual contributors. You may commit with any messages you find useful.
We always "Squash and Merge" Pull Requests into a single commit message when merging into the develop
branch.
The PR title and "Squash and Merge" commit message must be in the conventional commits format. The semantic-prs Github app is enabled for the repo and configured to require a PR title in the conventional commit format. When you "Squash and Merge", the commit message will automatically pull from the PR title, so just don't change this and there shouldn't be any issues. The conventional commit format is as follows:
<type>[optional scope]: <description> (#PR Number)
[optional body]
[optional footer(s)]
Example:
fix: reduce bundle size and check size in CI (#1234)
Co-authored-by: TinusLorvalds <lorvalds@finux-loundation.org>
Notice how the description is in lowercase (except for initialisms/acronyms). The description should be clear and concise. The subject line does not have to be fewer than 50 characters if making it shorter removes useful information.
Co-authors should be preserved.
This format is what drives our automated release process and helps makes releases go smoothly.