LabPack-C: A LabVIEW-Friendly C library for encoding and decoding MessagePack data

What is LabPack-C?

The LabPack-C project is a LabVIEW-friendly C library for encoding and decoding MessagePack data. The library is intended to be used with the Call Library Function node. This provides MessagePack encoding and decoding functionality to LabVIEW as a Dynamic Link Library (DLL, Windows), Dynamic Library (Dylib, macOS), and/or Shared Object (SO, Linux).

Install

A single ZIP archive containing the pre-compiled/built shared libraries for all of the platforms listed in the Build section is provided with each release.

1. Download the ZIP archive for the latest release. Note, this is not the source code ZIP file. The ZIP archive containing the pre-compiled/built shared libraries will be labeled: labpack-c_#.#.#.zip, where #.#.# is the version number for the release.
2. Extract, or unzip, the ZIP archive.
3. Copy and paste all or the platform-specific shared libraries to one of the following locations on disk:

Platform	Destination
Windows	C:\Windows\System32
macOS	/usr/local/lib
Linux	/usr/local/lib
NI Linux RT	/usr/local/lib

Build

Ensure all of the following dependencies are installed and up-to-date before proceeding:

• CMake 3.9.x, or newer
• Microsoft Visual C++ Build Tools 2017, Windows Only
• XCode Command Line Tools, macOS Only
• Git
• C/C++ Development Tools for NI Linux Real-Time, Eclipse Edition 2017, NI Linux RT only

Windows

The Microsoft Visual C++ Build Tools 2017 should have installed a x64 Native Build Tools command prompt. Start the x64 Native Build Tools command prompt. This ensures the appropriate C compiler is available to CMake to build the library. Run the following commands to obtain a copy of the source code and build both the 32-bit and 64-bit DLLs with a Release configuration:

> git clone https://github.com/fieldrndservices/labpack-c.git LabPack-C
> cd LabPack-c
> build.bat

The DLLs will be available in the build32\bin and build64\bin folders.

macOS

Ensure the command-line tools for XCode have been installed along with git before proceeding. Start the Terminal.app. Run the following commands to obtain a copy of the source code from the repository and build the dynamic library (dylib):

$ git clone https://github.com/fieldrndservices/labpack-c.git LabPack-C
$ cd LabPack-C
$ mkdir build && cd build
$ cmake ..
$ cd ..
$ cmake --build build --config Release

The dynamic library (.dylib) will be available in the build/bin folder.

Linux

If running on Ubuntu or similar distribution, ensure the build-essential, cmake, and git packages are installed before proceeding. These can be installed with the following command from a terminal:

$ sudo apt-get install build-essential cmake git

Start a terminal, and run the following commands to obtain a copy of the source code from the repository and build the shared object (so):

$ git clone https://github.com/fieldrndservices/labpack-c.git
$ cd labpack-c
$ mkdir build && cd build
$ cmake ..
$ cd ..
$ cmake --build build --config Release

The shared object (.so) will be available in the build/bin folder.

NI Linux RT

NI provides a cross-compiler for their Real-Time (RT) Linux distribution. Before proceeding, download and install the C/C++ Development Tools for NI Linux Real-Time, Eclipse Edition 2017. It is also best to review the Getting Stared with C/C++ Development Tools for NI Linux Real-Time, Eclipse Edition guide for more general information about configuring the internal builder.

1. Start NI Eclipse. A Workspace Launcher dialog may appear. Use the default.
2. A welcome screen may appear after the application has loaded. Close the welcome screen.
3. Right-click in the Project Explorer on the left and select Import from the context menu that appears. A new dialog will appear.
4. Select Git->Projects from Git from the dialog that appears. Click the Next > button. A new page will appear.
5. Select the Clone URI from the list that appears in the new page of the dialog. Click the Next > button. A new page will appear.
6. Enter the URI for the git repository in the URI: field, i.e. https://github.com/fieldrndservices/labpack-c.git. The Host: and Repository path: fields will populate automatically. Click the Next > button. A new page will appear.
7. Ensure only the master checkbox is checked in the Branch Selection page of the Import Projects from Git dialog. Click the Next > button. A new page will appear.
8. Browse to the workspace directory for NI Eclipse to populate the Directory: field. Leave all other fields as the defaults. Click the Next > button. A new page will appear.
9. Select the Import existing projects radio button from the options under the Wizard for project import section. Click the Next > button. A new page will appear.
10. Click the Finish button. No changes are needed on the Import Projects page. A new labpack-c project should appear in the Project Explorer.
11. Click the Build toolbar button (icon is a small hammer) to build the NI Linux RT x86_64-based shared object (so).
12. Click the drop-down menu next to the Build toolbar button and select the ARM build configuration. This will build the NI Linux RT ARM-based shared object (so).

Note, steps 3-10 only need to be done once to setup the project. The liblabpack-rt.so will be located in the x86_64 folder under the project's root folder inside the Eclipse workspace folder, and the liblabpack-arm-rt.so will be located in the ARM folder under the project's root folder inside the Eclipse workspace folder.

Tests

All of the tests are located in the tests folder. The tests are organized in "modules", where an executable is created that tests each source "module", i.e. writer, reader, etc. The tests are separated from the source, but the tests are built as part of build for the shared library. Each test executable is located in the bin\tests folder of the build directory and they can be run independently.

If the ctest, or make test on non-Windows systems, commands are used after building the tests to run the tests, then the ctest test runner framework is used to run the tests. This provides a very high level summary of the results of running all tests. Since the tests are organized into "modules" and suites, the ctest command only indicates that a test within a module and suite has failed. It does not indicate which test has failed. To investigate the failed test, the executable in the bin\tests folder for test module should be run. For example, if a test in the writer module failed, the ctest test runner will indicate the "writer" test has failed. The bin\tests\writer executable should then be run as a standalone application without the ctest test runner to obtain information about which test and assertion failed.

Windows

Start a terminal command prompt and navigate to the root folder of the project. Note, if following from the Build instructions, a command prompt should already be available at the root folder of the project. Enter the following commands to run the tests:

> ctest -C "Debug"

Or

> bin\reader
> bin\writer
> bin\status

macOS

Start the Terminal.app. Note, if following from the Build instructions, the Terminal.app has already been started and the present working directory (pwd) should already be the root folder of the project. Enter the following commands to run the tests:

$ ctest

Or,

$ bin/tests/reader
$ bin/tests/writer
$ bin/tests/status

Or,

$ make test

Linux

Start a terminal. Note, if following from the Build instructions, the terminal has already been started and the present working directory (pwd) should already be the root folder of the project. Enter the following commands to run the tests:

$ ctest

Or,

$ bin/tests/reader
$ bin/tests/writer
$ bin/tests/status

Or,

$ make test

License

Copyright (c) 2017 Field R&D Services, LLC.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the Field R&D Services nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY Field R&D Services, LLC ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Field R&D Services, LLC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Third-party maintained and licensed projects used by LabPack include:

• mpack: Copyright (c) 2015-2016 Nicholas Fraser
• minunit: Copyright (c) 2012 David Siñuela Pastor

mpack: A C encoder/decoder for the MessagePack serialization format

Copyright (c) 2015-2016 Nicholas Fraser https://github.com/ludocode/mpack

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

minunit - Minimal unit testing framework for C

Copyright (c) 2012 David Siñuela Pastor https://github.com/siu/minunit

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.