If you plan to contribute back to the community, making your code available via pull-request, please make sure to have read and understood theCommunity Documents and Contributor Guidelines.If you plan to distribute derived code, please follow ourlicensing guidelines.

Development in Docker is encouraged, for the sake of consistency and portability.By default, work should be built off ofnipreps/fmriprep:unstable, which tracks themaster branch, ornipreps/fmriprep:latest, which tracks the latest release version (seeBIDS-Apps execution guide for the basic procedure for running).

It will be assumed the developer has a working repository in$HOME/projects/fmriprep, and examples are also given forniworkflows andNiPype.

Patching a working copy into a Docker container¶

In order to test new code without rebuilding the Docker image, it is possible to mount working repositories as source directories within the container.TheDocker wrapper script simplifies this for the most common repositories:

-fPATH,--patch-fmriprepPATHworkingfmripreprepository(default:None)-nPATH,--patch-niworkflowsPATHworkingniworkflowsrepository(default:None)-pPATH,--patch-nipypePATHworkingnipyperepository(default:None)

For instance, if your repositories are contained in$HOME/projects:

$fmriprep-docker-f$HOME/projects/fmriprep/fmriprep\-n$HOME/projects/niworkflows/niworkflows\-p$HOME/projects/nipype/nipype\-inipreps/fmriprep:latest\$HOME/fullds005$HOME/dockeroutparticipant

Note the-i flag allows you to specify an image.

When invokingdocker directly, the mount options must be specifiedwith the-v flag:

-v$HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro-v$HOME/projects/niworkflows/niworkflows:/usr/local/miniconda/lib/python3.7/site-packages/niworkflows:ro-v$HOME/projects/nipype/nipype:/usr/local/miniconda/lib/python3.7/site-packages/nipype:ro

For example,

$dockerrun--rm-v$HOME/ds005:/data:ro-v$HOME/dockerout:/out\-v$HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro\nipreps/fmriprep:latest/data/out/outparticipant\-w/out/work/

In order to work directly in the container, pass the--shell flag tofmriprep-docker

$fmriprep-docker--shell$HOME/ds005$HOME/dockeroutparticipant

This is the equivalent of using--entrypoint=bash and omitting thefMRIPrep arguments in adocker command:

$dockerrun--rm-v$HOME/ds005:/data:ro-v$HOME/dockerout:/out\-v$HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep:ro--entrypoint=bash\nipreps/fmriprep:latest

Patching containers can be achieved in Singularity analogous todocker using the--bind (-B) option:

$singularityrun\-B$HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.7/site-packages/fmriprep\fmriprep.img\/scratch/dataset/scratch/outparticipant-w/out/work/

Adding dependencies¶

New dependencies to be inserted into the Docker image will either be Python or non-Python dependencies.Python dependencies may be added in three places, depending on whether the package is large or non-release versions are required.The imagemust be rebuilt after any dependency changes.

Python dependencies should generally be included in the appropriate dependency metadata of thesetup.cfg file found at the root of each repository.If some the dependency must be a particular version (or set thereof), it is possible to use version filters in thissetup.cfg file.

For large Python dependencies where there will be a benefit to pre-compiled binaries,conda packages may also be added to theconda install line in theDockerfile.

Non-Python dependencies must also be installed in the Dockerfile, via aRUN command.For example, installing anapt package may be done as follows:

RUNapt-getupdate&&\apt-getinstall-y<PACKAGE>

(Re)Building Docker image¶

If it is necessary to (re)build the Docker image, a local image namedfmriprep may be built from within the local repository.Let's assume it is located in~/projects/fmriprep:

~/projects/fmriprep$VERSION=$(pythonget_version.py)~/projects/fmriprep$dockerbuild-tfmriprep--build-argVERSION=$VERSION.

TheVERSION build argument is necessary to ensure that help text can be reliably generated.Theget_version.py tool constructs the version string from the current repository state.

To work in this image, replacenipreps/fmriprep:latest with justfmriprep in any of the above commands.This image may be accessed by theDocker wrapper via the-i flag, e.g.:

$fmriprep-docker-ifmriprep--shell

Code-Server Development Environment (Experimental)¶

To get the best of working with containers and having an interactive development environment, we have an experimental setup withcode-server.

1. Build the Docker image.We will use theDockerfile_devel file to build our development docker image:

$cd$HOME/projects/fmriprep$dockerbuild-tfmriprep_devel-fDockerfile_devel.

2. Run the Docker imageWe can start a docker container using the image we built (fmriprep_devel):

$dockerrun-it-p127.0.0.1:8445:8080-v${PWD}:/src/fmriprepfmriprep_devel:latest

If the container started correctly, you should see the following on your console:

INFOServerlisteningonhttp://localhost:8080INFO-NoauthenticationINFO-NotservingHTTPS

Now you can switch to your favorite browser and go to:127.0.0.1:8445 (or192.168.99.100:8445 for Docker Toolbox).

3. Copyfmriprep.egg-info into yourfmriprep/ project directoryfmriprep.egg-info makes the package executable inside the docker container.Open a terminal in vscode and type the following:

$cp-R/src/fmriprep.egg-info/src/fmriprep/

Code-Server Development Environment Features¶

• The editor isvscode

• There are several preconfigured debugging tests under the debugging icon in the activity bar

• seevscode debugging python for details.

• Thegitlens andpython extensions are preinstalled to improve the development experience in vscode.