How to set up an environment to develop or debug Bpipe
Helping Out
Bpipe is an open source project that anybody can contribute to. There are a variety of ways you can help, from adding documentation to providing feedback, but most of all, if you have skills in programming, you can help add new features to Bpipe.
Building Bpipe
While to run Bpipe you need only a Java Runtine Environment installed, to build Bpipe you need a couple more things:
- Install git if you don't already have it
- Clone the Bpipe source code using a command such as:
git clone https://github.com/ssadedin/bpipe
- Download and install a Java 1.8 SDK, add it to your PATH. A useful way to do this, especially if you have to manage multiple Java versions is to use SDKMan
Once you have these dependencies, you can go to the top directory that you cloned and type:
./gradlew dist
to compile and build Bpipe. A Bpipe distribution will be created in the build directory, however you can run Bpipe directly from the distribution directory by typing
./bin/bpipe
This should allow you to make changes to the Bpipe source code and to compile and create your own Bpipe distributions to use.
Note: in the past, it was necessary to first install Gradle and to download the JavaMail jar file. This is no longer necessary, as both are downloaded as automatically as needed (note that you must use the 'gradlew' command in the distribution directory rather than any build in installed gradle for this to work).
Running Tests
If you do make some changes you'll probably want (or at least, should want) to check if you broke some existing functionality. To do this, you can run the regression tests which live in the tests directory of the source distribution. To run the tests, change to the tests directory and just execute the "run.sh" command:
cd tests
./run.sh
The tests will take about 5 minutes to run. Please note that one test depends on having R installed, so if you do not have that you can expect a failure in that test.
Debugging
More than likely if you make any significant changes you will end up wanting to debug your code. The recommended way to do this is to launch Bpipe using 'debug' in place of 'run':
bpipe debug test.groovy input1.txt ....
The debug command will run Java in debug mode which will then wait for you to attach with a debugger that supports remote debugging such as eclipse. Just configure Eclipse to attach to the port printed out by the command.
Adding Documentation
Improving Bpipe's documentation is one of the easiest ways to help. Even small improvements such as clarifications, grammar fixes, or addition of examples are very much appreciated.
See DocumentationStyle for information about how to edit and test your documentation changes.