C++

Before you begin, please select your operating system below:

Operating system: Windows Linux (Ubuntu) Mac OS

Options

You can choose from two options for installing the library:

• Installer with prebuilt binaries
• Building from the source code

We recommend using the installer unless you are familiar with CMake and build tools of your platform. After installing the library, follow the instructions to setup and build your project.

Option 1: Installer

Ubuntu (Debian based)

If using our supported Ubuntu distribution, download the deb package depending on your platform:

• x64get_app
• armget_app
• arm64get_app

Install by clicking on the downloaded package or by using the dpkg command:

dpkg -i ZaberMotionCppInstaller-3.1.1-Linux_x64.deb

Non-Debian based distros

Download and run the .sh installer for your platform:

• x64get_app
• armget_app
• arm64get_app

Specify the install location for the installer. The suggested location is /usr/local.

chmod +x ZaberMotionCppInstaller-3.1.1-Linux_x64.sh
./ZaberMotionCppInstaller-3.1.1-Linux_x64.sh --prefix=/usr/local --exclude-subdir  # This command may need root privileges

Download and run the .pkg installerget_app.

Users who want additional control over their installation can use the .sh installerget_app instead.

Both installers contain universal binaries compatible with Intel (x64_86) based as well as Apple silicon (arm64) based Macs.

Download and run the installerget_app (recommended). The package contains 64bit (x64) binaries.

Additionally, we provide the 32bit (x86) installerget_app if you need to develop for this platform.

Please contact our customer support if the installer does not suit your use case.

Option 2: Build from the Source Code

We strongly recommend using "Option 1: installer" (above) unless you are familiar with CMake and the build tools of your platform. Our customer support offers only limited support for building the library from the source code.

Use your distributions package manager to install GCC, CMake and libprotobuf-dev.

• GCC should be version 4.9 or higher.
• CMake should be version 3.5 or higher.
• libprotobuf-dev should be version 3.6.1 or higher.

Verify the installed versions in your terminal:

g++ --version
# example output:
# gcc (GCC) 9.1.0
# Copyright (C) 2019 Free Software Foundation, Inc.
# This is free software; see the source for copying conditions.  There is NO
# warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

cmake --version
# example output:
# cmake version 3.14.5
# CMake suite maintained and supported by Kitware (kitware.com/cmake).

protoc --version
# example output:
# libprotoc 3.7.0

Use the homebrew package manager to install clang (llvm) and CMake.

• llvm should be version 9.0.0 or higher.
• CMake should be version 3.5 or higher.

brew install --with-toolchain llvm
brew install cmake

Download a compatible release from the protobuf github and follow the build instructions in the protobuf's src folder. (README) This will install the protobuf library.

• libprotobuf-dev should be version 3.6.1 or higher.

Verify the installed versions in your terminal:

g++ --version
# example output:
# gcc (GCC) 9.1.0
# Copyright (C) 2019 Free Software Foundation, Inc.
# This is free software; see the source for copying conditions.  There is NO
# warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

cmake --version
# example output:
# cmake version 3.14.5
# CMake suite maintained and supported by Kitware (kitware.com/cmake).

protoc --version
# example output:
# libprotoc 3.7.0

Ensure that you have Microsoft Visual Studio installed. Install CMake. When installing CMake please ensure that you select the "Add to system path" option.

• Visual Studio edition should be 2017 or later.
• CMake should be version 3.5 or higher.

Verify the installed versions in your command prompt:

cmake --version
# example output:
# cmake version 3.14.5
# CMake suite maintained and supported by Kitware (kitware.com/cmake).

Download the ZML source package.

Then open a command prompt and enter in the following commands. You will need to specify the system architecture when calling cmake, for most systems this is 64bit (x64). Note that if you wish to install the library (last step below) this command prompt must be started with admininstrator privileges.

# In the same directory as your unzipped source directory

# This path will change depending on the version of Visual Studio you have installed
call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\Tools\VsMSBuildCmd.bat"

cd ZaberMotionCppSource/cpp
mkdir build
cd build
cmake -G "Visual Studio 15 2017 Win64" ../ -DZML_ARCH=x64  # For visual studio 2019: `cmake -G "Visual Studio 16 2019" -A x64 ../ -DZML_ARCH=x64`
msbuild 'Zaber Motion Library.sln' /p:Configuration=Release
devenv 'Zaber Motion Library.sln' /build Release /project INSTALL  # Will require administrator privileges

The install step will place the libraries in C:\Program Files\Zaber Motion Library\.

Then use CMake to build and install the source in your terminal. You will need to specify the system architecture when calling cmake, for most systems this is 64bit (x64).

# In the same directory as your unzipped source directory
cd ZaberMotionCppSource/cpp
mkdir build && cd build
cmake ../ -DZML_ARCH=x64
make
make install  # This may require root privileges

Now you may create your project and start programming in C++. Continue the Getting Started guide by running the example code.

Now you may create your project and start programming in C++. Continue the Getting Started guide by initializing the library in your code.

Setting up a new Visual Studio Project

These instructions are for Visual Studio 2017, instructions for other versions may differ.

1. File menu -> New Project

2. Select C++ Console App or C++ Desktop App (These steps assume console app); If you don't have these options in the new project list, run the installer for your Visual Studio IDE and add support for C++ development.

3. Click Next, name your project and select a directory to put it in, then click Create.

4. When the project is created, Visual Studio should show you a .cpp file with a main() function already created to print "Hello World!". To test that your C++ environment is set up, try running this program without changes. If the output window closes too fast to see the results, go to the Tools menu -> Options -> Debugging and uncheck Automatically close the console when debugging stops. When you run the program you should now see the "Hello World!" Output.

5. Because the compiler will not automatically find the include files and library files for the Zaber Motion Library, you must specify them in your project settings: In the Solution Explorer window (View menu -> Solution Explorer if you don't see it), right-click on your program's project heading and select Properties.

   1. On the top of the dialog change Configuration to Debug and Platform to x64.

   2. Under VC++ Directories, edit the Executable Directories property, add a new line and browse to and select the bin directory of your ZML installation (probably C:\Program Files\Zaber Motion Library\bin). If this is a Debug build configuration provide a path to the debug library file instead (probably C:\Program Files\Zaber Motion Library\bin\Debug).

   3. Under VC++ Directories, edit the Include Directories property, add a new line and browse to and select the include directory of your ZML installation (probably C:\Program Files\Zaber Motion Library\include). You want to select the directory named "include", not any of its subdirectories such as "zaber".

   4. Under VC++ Directories, edit the Library Directories property, add a new line and browse to and select the lib directory of your ZML installation (probably C:\Program Files\Zaber Motion Library\lib).

   5. Under Linker -> Input, edit Additional Dependencies and add zml.lib.

   6. This will let you compile the program. To run, the program needs access to the DLLs. You can give the program access by going to Debugging and editing the Environment property and add the line: PATH=$(ExecutablePath);%PATH%.

   7. Note that the steps above need to be repeated for each configuration you want to build your program for.

6. Click OK.

7. In the top menu bar, set the "Solution Platform" to x64 and save your project.

Qt

You can use the installed library in a Qt project assuming you are using the Visual Studio compiler. Just add the following lines to your project file (.pro).

win32 {
    CONFIG(debug, debug|release) {
        LIBS +=  -L'C:/Program Files/Zaber Motion Library/bin/Debug'
    }
    CONFIG(release, debug|release) {
        LIBS +=  -L'C:/Program Files/Zaber Motion Library/bin'
    }

    LIBS += -L'C:/Program Files/Zaber Motion Library/lib' -lzml
    INCLUDEPATH += 'C:/Program Files/Zaber Motion Library/include'
    DEPENDPATH += 'C:/Program Files/Zaber Motion Library/include'
}

MinGW

If you are using the MinGW compiler, the library must be built from source code because the installed binaries are built for Visual Studio. While it is possible to build the library using MinGW compiler, we do not support this use case. Please take the following instructions without any warranty.

In order to build the library the MinGW distribution must support dynamic linking (-ldl). This is true of the MSYS2 distribution but not of some others. However, you may need to install some additional packages. Use the following commands to generate and build the project.

cmake -G "MinGW Makefiles" ../ -DZML_ARCH=x64
mingw32-make

You may need to change some of the source/generated files to achieve a working configuration.

Building your Project

When compiling a program that uses this library, you will need to link to the Zaber Motion Library. The library is named libzml. So the appropriate flag with gcc is -lzml.

For example:

g++ -std=c++11 zaberexample.cpp -o zaberexample -lzml

Troubleshooting

If you can't link to the library, you might need to run the ldconfig utility. Some distributions might need you to specify the specific directory that the lib was installed into.

# You may need to run these with root privileges
ldconfig
ldconfig /usr/local/lib

Building your Project

When compiling a program that uses this library, you will need to link to the Zaber Motion Library. The library is named libzml. So the appropriate flag with clang is -lzml.

For example:

clang++ -std=c++11 zaberexample.cpp -o zaberexample -lzml

Troubleshooting

If you installed the library into a non standard location, you may need to add that location to the path. See the dyld command for reference.

Updating

If you are already using the library and want to update to the latest version, you will have to reinstall the library.