Arm and disarm
Scribble supports instrumenting files in-place for interoperability with user-specific testing and deployment environments. This is specifed with the
--output-mode files
option. One use case for this mode is to run the user test suite on the instrumented code. For example lets assume we have these 2 files:Base.sol
contract Base {
}
Foo.sol
import "Base.sol";
contract Foo is Base {
/// #if_succeeds {:msg "P1"} y == x + 1;
function inc(uint x) public pure returns (uint y) {
return x+1;
}
}
We can instrument them in-place using the following command:
scribble Foo.sol --output-mode files
This would generate 2 new files -
Foo.instrumented.sol
and __scribble_ReentrancyUtils.sol
.Foo.instrumented.sol
is the instrumented counterpart ofFoo.sol
, and __scribble_ReentrancyUtils.sol
contains a helper contract. Now a user can manually swap Foo.instrumented.sol
with Foo.sol,
re-build their contracts and run tests on the instrumented contracts, and later swap the originals back. However these steps are tedious, which is why scribble
automates them with the --arm
and --disarm
options. We can add the --arm
option when instrumenting like so:scribble Foo.sol --output-mode files --arm --instrumentation-metadata-file md.json
Foo.sol -> Foo.sol.instrumented
Copying Foo.sol to Foo.sol.original
Copying Foo.sol.instrumented to Foo.sol
Scribble performed 4 steps:
- 1.Emit the instrumented version of
Foo.sol
-Foo.instrumented.sol
- 2.Make a copy of the original
Foo.sol
asFoo.original.sol
- 3.Replace
Foo.sol
withFoo.instrumented.sol
- 4.Emtited a json metadata file
md.json
that is used to keep track of what files were modifies for disarming.
At this point if you rebuild the contracts you would get the instrumented version of the code. To revert back to the original un-instrumented code its sufficient to run the same command with
--disarm
instead of --arm
:scribble Foo.sol --output-mode files --disarm --instrumentation-metadata-file md.json
Moving Foo.sol.original to Foo.sol
Removing Foo.sol.instrumented
Removing /home/dimo/work/consensys/tmp/test_pass/scribble-getting-started/installation_examples/__scribble_ReentrancyUtils.sol
Removing md.json
Note that as long as you are inside of a npm package directory structure, you don't need to specify the
--instrumentation-metadata-file
option. Scribble will automatically detect the project root (the nearest parent folder with a package.json) and place the instrumentation metadata file there). If a project root is not detected, scribble will throw an error asking you to specify --instrumentation-metadata-file
explicitly.Last modified 1yr ago