Tutorial¶

We assume a machine with a reasonably up to date operating system. NOTE: You may need to run the commands listed here with higher user privilege such as root i.e., prefix commands with sudo.

Install Dependencies¶

At the OS-level we require Python 2.7, Git, and Pip to function.

If your system does not have any of these see the installation page.

Install BLCI¶

Assuming all dependencies are installed simply clone BLCI from gitub and run the installation script as follows:

git clone https://github.com/neurodata/blci.git
cd blci/
./install

If this fails, look to the full installation guide for detailed installation instructions.

BLCI Use¶

For more comprehensive documentation on the BLCI interface and commands, please refer to the interface page.

Example repo/project¶

The following is a project with code and data that we use as a running example throughout this tutorial. To follow along we advise you to download it.

myrepo/
    code/
        a.py
        analysis/
            c.py
    data/
        data.txt
        databy2.txt
    otherdata/
        data.txt

NOTE: All paths are relative to $PROJECT_HOME, the root directory for your project.

Example `code` dir details of importance¶

The script code/a.py reads data/data.txt and writes data/databy2.txt
The script code/analysis/c.py reads

Create a `blci.yml` config file¶

At a minimum the configuration file needs to contain the language setting and BLCI will flesh it out as much possible, then users must complete it as necessary.

All configuration settings are documented on the configuration page.

language: python

Initialize (`init`) the repo¶

Execute:

./bl myrepo -i

BLCI initialization will result in a fleshed out, but often incomplete blci.yml file. In our case what we receive is:

language: python
version: 2.7
name: myrepo
description: A BrainLab Continuous Integration repo
code_loc:
- code
credentials: .credentials
data_dep:
    read: {}
    write: {}
data_loc:
- data
ignore: [.*, .pyc, .d, .o, .javac, .rbin, .mat]
nthread: 1
read:
- .py
- .ipynb
path: []

NOTE: The order of the settings does not matter, but the spacing matters when it comes to settings with lists as values.

BLCI also builds a code-to-code dependency metadata file that is saved as blci.deps. This should not be edited by users. This file notes any code-to-code dependencies within the repo. These are obtained from import/include statements.

Complete the configuration file¶

We must now specify all the data-to-code dependencies for the data files. First, we need to add the data and otherdata directories as data locations.

data_loc:
- data
- otherdata

Next, we need to indicate the following data dependencies:

data/data.txt is read by code/a.py and code/analysis/c.py
otherdata/data.txt is written by code/analysis/c.py
data/databy2.txt is written by code/a.py.

Here is how we would achieve this:

data_dep:
    read:
        data/data.txt:
            - code/a.py
            - code/analysis/c.py
    write:
        data/databy2.txt:
            - code/a.py
        otherdata/data.txt:
            - code/analysis/c.py

Modify `script` actions to justify `data_dep` settings¶

Now we add the script action that actually performs computation and supports the data_dep settings. The following is what a script value might look like for this example:

script:
    - python code/analysis/c.py data/data.txt 2.5 otherdata/data.txt
    - cd code && python a.py

Read over the script setting in Travis for details on what actions it triggers. Note that we use it not as a testing action, but instead an action to perform computation.

Add (`add`) the repo¶

Finally we need to add the repo as a BLCI repo. This action will:

Create a remote repo in Github for you with the name you specify (or it was given by default) as the name argument. The repo will also have a branch with the same name as your remote repo.
Create and track the remote repo with Travis-CI.

To perform this action execute:

./bl myrepo -a

Proceed to check https://travis-ci.org/ to ensure your repo is created correctly and builds.

Update BLCI repo¶

TODO: update instructions