Small library to control and read out lab equipment.

Table of Contents

• Getting the Code
  • Updating Submodules After Changing Branches
• labRemote Requirements
  • Additional Requirements
• Compiling labRemote
• labRemote Examples
• Contributing to labRemote
• Creating New labRemote Based Projects
• Python Bindings
  • Requirements for Python Bindings
  • Installation with pip
  • How to use the Python bindings

Getting the Code

You can obtain the code by checking out the labRemote repository:

git clone --recursive <url> # example url: https://gitlab.cern.ch/berkeleylab/labRemote.git

The --recursive flag checks out any of the labRemote external dependencies (e.g. nlohmann json). If you wish to work off of the non-default branch of labRemote, please see the next section on Updating submodules when changing branches.

Updating submodules after changing branches

Typical use cases involve cloning the labRemote repository following the command described in Getting the Code and then switching to another branch immediately after. Switching labRemote branches does not automatically update the submodules contained within labRemote to their respective commit histories of the labRemote branch that you switch to. Because of this, you must manually update the labRemote submodules when changing branches. The complete procedure then becomes:

git clone --recursive <url> # as before
cd labRemote
git checkout <branch-name>
git submodule update --init --recursive

At this point, the submodules will be at their commits corresponding to the branch <branch-name> as opposed to their state of the default branch checked out in the initial git clone call.

labRemote Requirements

The minimal requirements for compiling the labRemote code are those provided by a suitable C++ compiler. labRemote is written with C++11 in mind -- specificifcally, that provided by the default CentOS7 installation: gcc 4.8.5:

Additional Requirements

Additional external libraries may be necessary if you need to leverage specific labRemote libraries. These are specified in the table below. For those libraries not provided as labRemote submodules, it is expected that the user is responsible for installing them on their system if required.

One can also refer to the .gitlab-ci.yml file for a complete listing of installation and dependencies.

Compiling labRemote

Once you have checked out the labRemote repository, follow the usual cmake installation procedure:

cd path/to/labRemote/
mkdir build
cd build
cmake3 .. # Can be cmake outside of CentOS
make

labRemote Examples

Example programs using labRemote libraries are provided for in the src/examples directory. Upon successuful compilation, they should be available as executables under the installation directory (build/examples/).

Contributing to labRemote

See the project's CONTRIBUTING page for complete info.

Creating New Projects

You can add labRemote as a submodule and create a new project. All projects should be labRemote-apps. An example labRemote-app is provided for by ExampleLabRemoteProject

Python Bindings

Python bindings to the labRemote target can be enabled either by setting the flag -DUSE_PYTHON=on during the cmake compilation step or via pip.

Requirements for Python Bindings

A python version >=3.6 is required in order to build the python bindings for labRemote. Ensure that you have the needed python source files and development packages installed on your system.

On CentOS this can be achieved with:

yum install python3-devel

More information on how to install python can be found here.

Installation with pip

You can build the labRemote python bindings using pip. There are two ways you can do this:

• Method Number One: requires that you first clone the labRemote repository as usual
• Method Number Two: does not require that you manually clone labRemote

The two methods are outlined below.

Method Number One

This method assumes that you have cloned the labRemote repository and is the method to use if you need to have the labRemote C++ source code and/or utilities available in addition to using the python bindings. For example, if you are a developer you should follow this method.

The method is outlined here:

cd /path/to/labRemote 
python3 -m venv myenv
source myenv/bin/activate # start the virtual environment
{myenv} python -m pip install -U pip
{myenv} python -m pip install .
{myenv} python -c "import labRemote"

Note that you are not absolutely required to follow the usual CMake build procedure in order for the steps above to succeed: the necessary build for the labRemote module occurs during the pip install . step. Of course, if you wish to use the C++ utilities you will still need to compile labRemote as usual even after following the above steps.

Method Number Two

This method does not require that you have cloned the labRemote repository beforehand, and is as follows:

python3 -m venv myenv
source myenv/bin/activate # start the virtual environment
{myenv} python -m pip install -U pip
{myenv} python -m pip install git+https://gitlab.cern.ch/berkeleylab/labRemote.git@devel
{myenv} python -c "import labRemote"

How to use the python bindings

Examples of how to use the labRemote python bindings are provided in the examples directory, where you will find python versions of existing C++ labRemote examples.