Installing Node Libraries

Posted by Ashley Anderson on Tue 30 June 2015

One of the nicest features of GPI is how easy it is to add a library and begin using new nodes. Whether the library contains nodes and networks you created, or code from a collaborator or colleague, installation is the same simple process.

Here we cover installing an updated version of the Core library. This will serve as a general demonstration of how to install additional node libraries.

The .gpirc File

GPI searches for libraries (by default) in a ~/gpi/ directory within your home directory. On Mac OS X, the full path of this folder is /Users/<username>/gpi/, and on Ubuntu (and most flavors of Linux) it is /home/<username>/gpi/. Thus, to install a new library, simply move its root directory into this folder. New libraries are imported automatically any time GPI is started.

The ~/.gpirc file contains per-user configuration options for GPI. Since the file is hidden (begins with a .), you will not see it in a normal directory listing; use ls -a to see it. If this file does not exist on your system, you can generate a basic version from the GPI "Config" menu.

fitw75

Select "Generate Config File" to create a basic .gpirc file.

The default GPI library path (~/gpi/) is stored in the LIB_DIRS variable within the .gpirc file. You can amend the LIB_DIRS in your .gpirc file to tell GPI to look for libraries in some other directories, if you prefer. Append (or prepend) directories to LIB_DIRS separated by colons.

fitwidth

My .gpirc file with modified LIB_DIRS to include additional node libraries.

Installing the Updated Core Library

The GPI package includes a snapshot of the Core node library, but new versions of the Core nodes are maintained on GitHub. Installing the updated Core library will not override the default installation of the Core library, so you need to remove its path (/opt/gpi/node/core/) from the LIB_DIRS variable in your .gpirc file. A current snapshot of the Core library can be downloaded as a zip archive from main GitHub page. To install this snapshot, simply unzip the archive into ~/gpi/core/ as described above.

To stay up-to-date with the latest changes, it is recommended to link your local Core library with the remote repository by cloning it using Git. Git is a popular version control system, available on all platforms. Using Git makes it easy to update your local copy of the source code, and to contribute back your own enhancements and bug fixes.

To install the Core library using Git, open a terminal session and execute the following commands (after installing Git if necessary):

% cd ~/gpi
% git clone https://github.com/gpilab/core-nodes.git core


This will create a copy of the remote core-nodes repository to your computer, inside your default GPI library directory.

Compiling the Core Library

GPI includes a Python/C++ interface called PyFI. The Core library uses PyFI to implement algorithms in a combination of C++ and Python code. GPI includes a script (gpi_make) to help compile C++ files associated with a GPI library.

Compiled binary objects are not included in the Git repository, so it's necessary to build the library after installation. Once you have downloaded or cloned the repository into ~/gpi/core/, run the following commands to compile the C++ code:

% cd ~/gpi/core
% gpi_make --all

Updating the Core Library

As mentioned, Git makes it easy to update the Core library with any new changes from the developers. If you cloned the repository using Git, you can update your copy of the Core library using the following commands:

% cd ~/gpi/core
% git pull
% gpi_make --all


Running git pull fetches any new changes from the core-nodes repository on GitHub, and merges them into your local copy. To finish updating, it's also good idea to re-compile the C++ code in case any changes were made. Note you may get some warnings or errors if you attempt to "pull" changes after modifying the code yourself. If you have changes you'd like to keep (or contribute back!) please fork the project on GitHub, or just get in touch!

Branches in the core-nodes Repository

Development in the core-nodes repository follows the gitflow branching model. There are two main branches in this model: master, which contains stable releases; and develop, which contains newer, untested changes. Most likely you will want to keep your local copy on the master branch, unless you are planning to make changes to the library and contribute them back to the community.

Use git branch to see which branch you are on, and git checkout <branch name> to switch to a different branch. You will again want to recompile (gpi_make --all) any time you change branches.


Hopefully this will help you collaborate and stay up-to-date with the latest changes in your GPI node libraries. Check out the documentation for more information, and please get in touch if you have questions or if you're interested in contributing to the project.