Before you begin

This project is an example of a BioLockJ module.

To build it, or even just to use it, you must have successfully installed and tested BioLockJ.

biolockj --version
biolockj ${BLJ}/templates/myFirstPipeline/myFirstPipeline.properties

For more information about how to create BioLockJ modules and for other examples, see the BioLockJ external modules resource repository

Use this module (the latest release)

See the userguide pages for the modules in this project.

Download the jar file to your external modules folder (mods), which you point to with the --external-modules argument. In your config file, reference the ShowBljVars module in your module run order using the #BioModule keyword.

Minimalist example:

PROJ=ShowTestVar
URL=https://github.com/BioLockJ-Dev-Team/ShowTestVar/releases/latest/download
CONFIG=printBlj.config

mkdir ${PROJ}_Example
cd ${PROJ}_Example
wget $URL/${PROJ}.jar -P $PWD/mods
wget $URL/demo.zip
unzip demo.zip && rm demo.zip 
biolockj --external-modules $PWD/mods ./demo/$CONFIG

The example above will create a minimalist pipeline demonstrating the use of the ShowBljVars module from the ShowTestVar project.

Add the #BioModule line for the ShowBljVars module to any other pipeline.

Build this project from the latest source code

Download the source code:

wget https://github.com/BioLockJ-Dev-Team/ShowTestVar/archive/refs/heads/main.zip 
unzip main.zip && rm main.zip && mv ShowTestVar-main ShowTestVar

Alternatively, use git:

# git clone https://github.com/BioLockJ-Dev-Team/ShowTestVar.git

Note: The build file references the BioLockJ project using the $BLJ variable. There is an option to use a relative path instead, see commented lines in the build.xml.

Run the ant command from the project root directory.

cd ShowTestVar
ant

If you encounter build difficulties, try using the docker build process below.

Test that BioLockJ recognizes the module.

biolockj-api listModules --external-modules $PWD/dist

The output list should include "com.github.fodorlab.envVar.ShowTestVar".

Run a demo pipeline.

biolockj --external-modules $PWD/dist ./demo/printBlj.config

Check the demo folder for more examples.

Build the project and its documentation using docker

Confirm docker is running:

docker run --rm hello-world

This is the standard build process for BioLockJ modules.

Note: the code block below uses $PWD (path to current working directory), and should be run from the project root directory; the folder you downloaded in the previous section.

docker run --rm \
  -v $PWD:/project \
  -v $BLJ:/BioLockJ \
  -e BLJ=/BioLockJ \
  -w /project \
  biolockjdevteam/build_and_deploy \
  ant userguide

This process produces the jar file and the standardized userguide pages for the modules in this project.

IF you are also building BioLockJ from source code, use the same docker image to build the BioLockJ project before building this project:

# git clone https://github.com/BioLockJ-Dev-Team/BioLockJ.git
# cd BioLockJ
# BLJ=$PWD
docker run --rm -v ${BLJ}:/biolockj biolockjdevteam/build_and_deploy

Using the same docker image for both builds reduces the chances of conflicts arising from different java/host versions.

---

This is a template

This project has all the components we typically expect to see for a third-party BioLockJ module.

Notice that this repository is a template repository. To make your own BioLockJ module, you can copy this reposiotry to start from its files and structure, test the build process, and modify from there to make your own module.

Run through the instructions below to make sure your system is set up correctly to run BioLockJ and use external modules.

In your own copy of this README, delete the section "This is a template", and update other instructions to reference your own repo.

Pre-release instructions

By convention, a release is a static point, a version. For reproducible results, use the the latest release of all software components.

Sometimes you may want to allow your collaborators to test your module without having to build it. This is often the case leading up to a release.

Minimalist example:

PROJ=ShowTestVar
URL=https://raw.githubusercontent.com/BioLockJ-Dev-Team/ShowTestVar/main
CONFIG=printBlj.config

mkdir ${PROJ}_demo
cd ${PROJ}_demo
wget ${URL}/dist/${PROJ}.jar -P $PWD/mods
wget ${URL}/demo/printBlj.config -P $PWD/demo
biolockj --external-modules $PWD/mods ./demo/${CONFIG}

Release process

Build your jar file using the ant build process:

cd ShowTestVar
ant jar

Compress your demo folder using:

cd ShowTestVar
zip -r -X demo.zip demo

Create a release in github: go to tags, find option to create a new release.
Upload the jar file and the demo.zip file as release artifacts.

Update the instructions in your README accordingly. Sometimes you may reference a specific release, but most documentation will reference the "latest" one using the https://github.com/<user>/<repo>/releases/latest format.