Building solc‐js from source

This is a little how-to of how to build and test solc-js.

Installing dependencies

npm install 

Building

npm run build

Updating the soljson.js version to the latest release

The script below downloads and update the soljson.js file located at the root directory. Please, remember to run npm run build again after downloading it to ensure that your tests will run with the new version.

npm run updateBinary

Testing

npm run test

Using different soljson.js in solc-js test

Download the desired soljson.js version to the root directory of solc-js and build the project. The build process will copy the downloaded soljson.js to dist/soljson.js. For example, if you want to use a version of soljson.js generated by the Solidity CI, navegate through the CircleCI workflow pipelines of the desired PR, and search for the job b_ems. The generated binary soljson.js will be under the Artifacts tab in the CircleCI workflow dashboard.

cd solc-js
wget https://output.circle-artifacts.com/output/job/6318ee25-a6ee-4134-b535-5541854e2e8a/artifacts/0/soljson.js -O soljson.js
# the test script automatically runs the build.
npm run test

Please note that some tests use specific solc version. See https://github.com/ethereum/solc-js/blob/master/test/compiler.ts#L879 for some examples.

You can also copy the soljson.js version created by the solidity compiler from your local build. For that, ensure that you have build the Solidity with Emscripten by running the following script in your Solidity fork:

cd solidity
./scripts/build_emscripten.sh

The script will build a docker image with the required build dependencies and it will create soljson.js file under the Solidity root on a successful build.

Testing version of soljson.js

The script below assumes that soljson.js is in the same folder where the script is executed.

cat <<-EOF > test-soljson.sh
#!/usr/bin/node --wasm-dynamic-tiering
var solc = require('./soljson.js')
// low-level wasm api call
console.log(solc.cwrap('solidity_version', 'string', [])())
EOF

chmod +x test-soljson.sh
./test-soljson.sh

Running specific set of tests

For that you need to invoke tape directly, for example:

# to invoke the tape installed from the package.json of solc-js
npx ts-node node_modules/tape/bin/tape test/smtchecker.ts

# to invoke a tape instalation on your computer
tape test/smtchecker.ts

You can also specify specific tests using the only keyword. Note that this may not run as expected when running the tests using npm run test, since test/index.js imports test/compiler.js which downloads and run some tests for old compiler versions everytime it is executed.

For instance, if you add only to the following test:

diff --git a/test/smtchecker.ts b/test/smtchecker.ts
index 7019333..98dfa78 100644
--- a/test/smtchecker.ts
+++ b/test/smtchecker.ts
@@ -54,7 +54,7 @@ tape('SMTChecker', function (t) {
   });
 });

-tape('SMTCheckerWithSolver', function (t) {
+tape.only('SMTCheckerWithSolver', function (t) {
   // In these tests we require z3 to actually run the solver.
   // This uses the SMT double run mechanism instead of the callback.

And run:

npx ts-node node_modules/tape/bin/tape test/smtchecker.ts

The output should be similar to:

TAP version 13
# SMTCheckerWithSolver
# Simple test with axuiliaryInputRequested
ok 1 should be truthy
ok 2 should not be equal
ok 3 should be truthy
ok 4 should be equal

1..4
# tests 4
# pass  4

# ok

See some examples here: https://github.com/tape-testing/tape/blob/9a47abae189019797a8cfd504b5194ba4ecdf1a9/test/no_only/test-b.js#L8

If you would like to see traces or other debug info from nodejs, you can use NODE_OPTIONS environment variable (see: https://nodejs.org/api/cli.html#node_optionsoptions for more details and available options). For example:

NODE_OPTIONS="--trace-warnings --trace-uncaught" npx ts-node node_modules/tape/bin/tape test/smtchecker.ts

Increasing Javascript heap memory

In some cases, when testing hardhat tests you may need to temporarily increase the Javascript heap memory to avoid out of memory errors. See: https://github.com/NomicFoundation/hardhat/issues/3471 for context.

export NODE_OPTIONS="--max-old-space-size=4096"