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.
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.
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.