How to Reuse Code from other Abaci Projects#

Abaci makes it easy to reuse code from other Abaci compatible repositories.

This is useful for keeping common code centralised in separate repositories and therfore avoid code-duplication across multiple projects.

Using abaci dependencies to centralise common code also makes it easier to push updates to multiple projects that depend on the same common code.

Prerequisites: you must have Git installed and available at the command line

Setup a Project for Reuse#

If you would like to reuse code from a source project, that project must first satisfy the following criteria:

  1. Be accessible via a git remote repository (e.g. GitHub/GitLab)

  2. Have an abaci.toml configuration file in the repository root folder that contains:

    • a name field in the abaci.toml AND;

    • source files specified in the include or sources fields

Important

You cannot use code from the top-level user subroutine of a source project, only from source files that it specifies in the include and sources section of the configuration file.

  • This is to avoid multiple definition of the main user subroutine interface (i.e. vumat,vdisp,vexternaldb)

  • If you have a top-level user subroutine file, you should modularise your code so that reusable functions and subroutines are in separate module files. See Using Fortran Modules.

Using a Remote Dependency#

Once you have a source project setup as described above, you can specify it as a remote dependency in the configuration file abaci.toml as follows:

[[dependency]]
name = "<name>"
git = "<git-url>"
version = "<tag|commit>"

Where:

  • <name> matches the name field in the source project

  • <git-url> is the url address for the source project remote repository on GitHub or GitLab

  • <tag|commit> is either a version tag or git commit hash from the remote repository

Example:

[[dependency]]
name = 'matrix-utils'
git = 'git@github.com:BristolCompositesInstitute/matrix-utils-library.git'
version = '001a415b2e587ee545b1cd69169699f9eed77a65'

Once you have updated your abaci.toml configuration file, you can verify that the dependency has been specified correctly by running the command:

  abaci show sources

to show a list of source files available. You should see a list of source files in the current project as well as source files provided by the source project dependency.

Example:

  abaci show sources
   [user-sub] usub.f
   [included] CDM_functions.f90
   [included] matrix-utils/matrix_lib.f90

Note: files from the source project will be in a subfolder named after the source project name

Once you have checked that dependency source files are available, you should include them into your top-level user subroutine file - don’t forget to prefix the filenames with the source project name and a forward-slash:

Example:

#include "matrix-utils/matrix_lib.f90"

Notes on using Dependencies#

  • If the version field for the dependency changes, then abaci will automatically fetch the updated version, unless you have modified the dependency source files

  • Source files for the dependencies are downloaded into a dependencies folder

    • You may modify source files for dependencies to get it working with your code, however you should always push these changes to the original source project repository so that they can be accessed by other users

  • If your dependency requires a username and password to access, consider using SSH to specify the dependency URL instead of HTTPs, see here for more information.