From 5547c2b530706026c459b14d48a14fbf084aa065 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Mon, 29 Jul 2019 13:09:31 -0700 Subject: [PATCH 1/3] Add truffle library documentation --- .../writing-external-scripts.md | 40 ++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/src/docs/truffle/getting-started/writing-external-scripts.md b/src/docs/truffle/getting-started/writing-external-scripts.md index a251abb09..449226796 100644 --- a/src/docs/truffle/getting-started/writing-external-scripts.md +++ b/src/docs/truffle/getting-started/writing-external-scripts.md @@ -80,7 +80,7 @@ know how we can improve it! // config_[1] starts remaining parameters. if (config.help) { console.log(`Usage: truffle run hello [name]`); - done(null, [], []); + done(null, [], []); return; } @@ -105,3 +105,41 @@ know how we can improve it! ``` npm publish ``` + +## Importing Truffle as a module + +```javascript +const truffle = require("truffle"); +``` + +Beginning with `v5.0.30`, Truffle exports the methods listed in [truffle-core/index.js](https://github.com/trufflesuite/truffle/blob/develop/packages/truffle-core/index.js). This means +your plugin can consume the user's Truffle instance as a library and access a subset of its internal command APIs. + +These are useful if you need to touch several Truffle commands in succession. For example, imagine a plugin that evaluated how a contract system performed at different levels of solc optimization. Its workflow might look like: +``` +for a range of solc settings: + compile contracts to a temp folder + run user's tests using the temp artifacts + measure and save gas usage data + +aggregate data and report +``` +The Truffle library lets you do this without making the user add configuration or string their own commands together. + +:warning: **Important Note** :warning: + +Truffle does not guarantee its internal APIs will follow semver. You should be prepared for your user +to run any Truffle version and handle mismatches gracefully. By using the library **you are entering into a gentleperson's agreement** to manage API volatility and other contingencies on your user's behalf. Some tips: + ++ Always `require` Truffle in a try/catch block ++ At runtime, verify the API components you need are actually exposed ++ Consume separately published (and semver guaranteed) Truffle modules when possible ++ Add yourself to the Truffle repo watch list on GitHub and keep abreast of internal changes that +might affect you. ++ Do not go on vacation + + + + + + From ab8185915db29460c1878f68890c27461d87c02f Mon Sep 17 00:00:00 2001 From: cgewecke Date: Tue, 13 Aug 2019 15:33:55 -0700 Subject: [PATCH 2/3] Update src/docs/truffle/getting-started/writing-external-scripts.md Co-Authored-By: g. nicholas d'andrea --- src/docs/truffle/getting-started/writing-external-scripts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/truffle/getting-started/writing-external-scripts.md b/src/docs/truffle/getting-started/writing-external-scripts.md index 449226796..ea24a5c7d 100644 --- a/src/docs/truffle/getting-started/writing-external-scripts.md +++ b/src/docs/truffle/getting-started/writing-external-scripts.md @@ -129,7 +129,7 @@ The Truffle library lets you do this without making the user add configuration o :warning: **Important Note** :warning: Truffle does not guarantee its internal APIs will follow semver. You should be prepared for your user -to run any Truffle version and handle mismatches gracefully. By using the library **you are entering into a gentleperson's agreement** to manage API volatility and other contingencies on your user's behalf. Some tips: +to run any Truffle version and handle mismatches gracefully. By using the library **you are entering into a gentleperson's agreement** to manage API volatility and other contingencies on your users' behalf. Some tips: + Always `require` Truffle in a try/catch block + At runtime, verify the API components you need are actually exposed From f2d0e9d5d5aab4cdf174224a8a9f7197998c4f6d Mon Sep 17 00:00:00 2001 From: cgewecke Date: Tue, 13 Aug 2019 15:36:51 -0700 Subject: [PATCH 3/3] Remove extraneous callback in plugin example --- src/docs/truffle/getting-started/writing-external-scripts.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/docs/truffle/getting-started/writing-external-scripts.md b/src/docs/truffle/getting-started/writing-external-scripts.md index ea24a5c7d..b838304a0 100644 --- a/src/docs/truffle/getting-started/writing-external-scripts.md +++ b/src/docs/truffle/getting-started/writing-external-scripts.md @@ -80,7 +80,6 @@ know how we can improve it! // config_[1] starts remaining parameters. if (config.help) { console.log(`Usage: truffle run hello [name]`); - done(null, [], []); return; }