University of Connecticut University of UC Title Fallback Connecticut

Installing BeagleLib

Downloading and building BeagleLib

Start by downloading the file beagle-lib-master.zip from the BeagleLib GitHub site. Unzip the library and move the resulting directory, beagle-lib-master, to a location of your choice. I will refer to this directory as BEAGLELIB_ROOT in the instructions that follow. For example, on my Mac, BEAGLELIB_ROOT=/Users/plewis/Documents/libraries/beagle-lib-master and, on my PC, BEAGLELIB_ROOT=C:\Users\plewis\Documents\libraries\beagle-lib-master.

Windows

  • Navigate to BEAGLELIB_ROOT and open the BEAGLELIB_ROOT\project\beagle-vs-2012\libhmsbeagle.sln Visual Studio solution. Visual Studio Community (VSC) will issues some warnings and will say "One or more projects in the solution were not loaded correctly…", but then will give you the opportunity to upgrade, which you should do.
  • Click on Solution Explorer tab on the left side of VSC, then click once on the libhsmbeagle project to select it.
  • Choose Build libhmsbeagle under the Build menu.
  • The last line of the output window should say "Build: 2 succeeded, 0 failed, 0 up-to-date, 0 skipped". If instead it says "Build: 1 succeeded, 1 failed, 0 up-to-date, 0 skipped", it probably means that you do not have Java installed. In this case, you will need to prevent VSC from attempting to build the JNI part of the libhmsbeagle project. Expand (using the right-pointing triangle symbol) the libhmsbeagle project within the libhmsbeagle solution in the Solution Explorer. Within the libhmsbeagle project you should see a libhmsbeagle folder containing 2 subfolders named JNI and plugin, along with files named beagle.cpp, beagle.h, BeagleImpl.h and platform.h. Expand the JNI folder and for each of the 2 files inside (beagle_BeagleJNIWrapper.cpp and beagle_BeagleJNIWrapper.h), right-click the file, choose Properties, then choose the value yes for Excluded From Build. When you are done, both of these files will have a tiny red minus sign symbol beside their name in the Solution Explorer.
  • Once compilation is completed, you should find a BEAGLELIB_ROOT\project\beagle-vs-2012\Debug folder containing several files, including these 3: hmsbeagle32D.dll, hmsbeagle-cpu32D-21.dll, and libhmsbeagle.lib. The two dynamic link library (dll) files contain code that is loaded when needed by the operating system (that is, most of the functionality in BeagleLib will not be in our program strom, but strom has access to it when it needs it). We will tell our strom project about the last (lib) file because it allows strom to know what functions are available to it in the dlls.
  • You can now close the BEAGLELIB_ROOT\project\beagle-vs-2012\libhmsbeagle.sln solution and open the strom solution again.
  • In the Solution Explorer within the strom solution, right-click on the strom project and choose Properties. Here are the property settings you need to change:
    • In the VC++ Directories section, add BEAGLELIB_ROOT to Include Directories (remember that we are using BEAGLELIB_ROOT to stand for the full path to the directory containing the BeagleLib code, so you should not type the word BEAGLELIB_ROOT directly; instead, use the button to locate the BeagleLib directory).
    • In the VC++ Directories section, add BEAGLELIB_ROOT\project\beagle-vs-2012\Debug to Library Directories
    • In the Linker/Input section, add libhmsbeagle.lib to Additional Dependencies.

Now you have a choice: do one of the following two things to ensure that BeagleLib DLLs will be available to your program when it runs:

  • Edit the system environmental variable Path so that it begins with the directory BEAGLELIB_ROOT\project\beagle-vs-2012\Debug. Be sure to separate it from the next directory specified in Path by a semicolon (;). To modify system environmental variables, on Windows 10 click the Start button, then Settings, type the word "Environment" into the search box, select Edit the system environmental variables, click the Environmental Variables… button, select Path in the list of System variables, press the Edit… button, and type in the directory containing the 2 BeagleLib DLL files (hmsbeagle32D.dll and hmsbeagle-cpu32D-21.dll).
  • Copy the two BeagleLib DLL files hmsbeagle32D.dll and hmsbeagle-cpu32D-21.dll from BEAGLELIB_ROOT\project\beagle-vs-2012\Debug to the Debug directory containing your strom.exe file.

Mac

Navigate to BEAGLELIB_ROOT and type these commands:

./autogen.sh
./configure prefix=$HOME
make
make install

If the first of these commands fails, then you need to install autotools. To do this, install HomeBrew and then issue this command (see also the instructions in the BeagleLib README file):

brew install automake autoconf pkgconfig libtool

After completing make install, several files whose names begin with libhmsbeagle- will be deposited in the lib subdirectory of your home directory.

To tell Xcode about this library:

  • Click on the blue icon labeled strom at the top of the Project Navigator, then click on the black icon labeled strom under TARGETS, and finally click on the Build Phases tab. Click the + sign in Link Binary With Libraries and choose the libhmsbeagle.dylib file in $HOME/lib.
  • Add an entry named BEAGLELIB_ROOT to Xcode > Preferences… > Locations > Source Trees and assign it to path $HOME/include/libhmsbeagle-1.
  • Add $(BEAGLELIB_ROOT) to the Header Search Paths in the Build Settings pane
  • Add $HOME/lib to the Library Search Paths in the Build Settings pane
  • Add :$HOME/lib to the end of the DYLD_LIBRARY_PATH environmental variable defined in the Arguments pane of the current scheme (choose Edit Scheme… after clicking on the button labeled strom beside the run/stop buttons at the very top of the Xcode main window). The full definition of DYLD_LIBRARY_PATH should thus be:
    $(BOOST_ROOT)/stage/lib:$HOME/lib
    
  • You are now ready to begin writing code that depends on BeagleLib!