Libra: An open-source "Methodology Discovery" Library


Installation: summary of changes to go from Cygwin (default) settings to Linux settings


We assume you are in the rood directory of the Libra code, so the reference to the files will be w.r.t. that path. Also, the examples below are specific to the group/system at UB - you need to use the corresponding counterparts specific to your system.

  1. CMakeLists.txt
      Linux:
      ADD_DEFINITIONS("-Wall")
    #  ADD_DEFINITIONS("-Wall -DCYGWIN")
    
      Cygwin:
    #  ADD_DEFINITIONS("-Wall")
      ADD_DEFINITIONS("-Wall -DCYGWIN")
    			
  2. CMakeLists.txt
      Linux:
    #FIND_PACKAGE(PythonLibs 2.6.8 EXACT REQUIRED)
    FIND_PACKAGE(PythonLibs 2.7.0 REQUIRED)
    
    
      Cygwin:
    FIND_PACKAGE(PythonLibs 2.6.8 EXACT REQUIRED)
    #FIND_PACKAGE(PythonLibs 2.6.8 REQUIRED)
    
    			
  3. src/CMakeLists.txt
      Linux:
    SET( ext_libs ${Boost_LIBRARIES} ${PYTHON_LIBRARIES}) #/libpython2.6.dll )
    #SET( ext_libs ${Boost_LIBRARIES} ${PYTHON_LIBRARIES}/libpython2.6.dll )
    
      Cygwin:
    #SET( ext_libs ${Boost_LIBRARIES} ${PYTHON_LIBRARIES}) #/libpython2.6.dll )
    SET( ext_libs ${Boost_LIBRARIES} ${PYTHON_LIBRARIES}/libpython2.6.dll )
    
    			
  4. src/mmath/meigen/CMakeLists.txt
      Linux:
    #set(EIGEN_INCLUDE /home/Alexey_2/Soft/eigen-eigen-2249f9c22fe8/)
    set(EIGEN_INCLUDE /projects/academic/alexeyak/Software/Eigen/eigen-eigen-bdd17ee3b1b3)
    
      Cygwin:
    set(EIGEN_INCLUDE /home/Alexey_2/Soft/eigen-eigen-2249f9c22fe8/)
    #set(EIGEN_INCLUDE /projects/academic/alexeyak/Software/Eigen/eigen-eigen-bdd17ee3b1b3)
    
    			
  5. src/solvers/CMakeLists.txt
      Linux:
    #SET( EIGEN_INCLUDE /home/Alexey_2/Soft/eigen-eigen-2249f9c22fe8/ )
    set(EIGEN_INCLUDE /projects/academic/alexeyak/Software/Eigen/eigen-eigen-bdd17ee3b1b3/)
    
      Cygwin:
    SET( EIGEN_INCLUDE /home/Alexey_2/Soft/eigen-eigen-2249f9c22fe8/ )
    #set(EIGEN_INCLUDE /projects/academic/alexeyak/Software/Eigen/eigen-eigen-bdd17ee3b1b3/)
    			
  6. Copy Python files included in Libra to the binary (build) directory. From _build directory
    make copy-libra-py
  7. In .bash_profile file
    # Libra
    export PYTHONPATH=/home/Alexey_2/Programming/Project_libra/_build/src:$PYTHONPATH
    export LD_LIBRARY_PATH=/home/Alexey_2/Programming/Project_libra/_build/src:$LD_LIBRARY_PATH
    		   
    Here, we assume that the binary (build) directory is /home/Alexey_2/Programming/Project_libra/_build/src

    Restart your terminal for the changes to PYTHONPATH and LD_LIBRARY_PATH to take effect

Installation


  1. Download the package from the GitHub repository (link) Older code is also available at SourceForge repository (link). Note, however, that the SourceForge is now considered a "backup" location, so may be updated less frequently than the GitHub.
    Lets say your top-level directory will be "libracode". In this directory you will find the following items:
    • src - this is the directory containing the source code to be compiled
    • tests - this directory contains a collections of what i call test-tutorials. Each test-tutorial both helps the developer to verify and validate the implementation, so it is usually created along the way of implementing some new feature of the Libra code. Once finished by the developer, the resulting testing script becomes a tutorial script - showing a new user the new implemented feature and how to use it. Along the way, other features of the Libra package maybe showcased, contributing to the wider learning of the new user. We will come back to this directory shortly - when we will be ready
    • doc - the directory containing some documentation and theory regarding the methods implemented in Libra
    • cmake - the cmake scripts for finding some necessary packages - not yet fully functional, will be taken care of later
    • .gitignore - we use GIT tool to control versioning of the code and keep track the history of development. This file simply excludes some types of the files we may have in the development directory (here and in all deeper levels). Usually, these are object files or other large and temporary files (e.g. output of test calculations, etc.). The dot in the beginning of the filename makes this file "invisible" (hides it) on Unix-type systems. This minimizes chances you delete it unintentionally.
    • CMakeLists.txt - this is the main file that defines how to build the Libra code using cmake utility. It defines all external packages, setups, options, etc. You need to customize it for your particular environment. This is the file we will have to deal with in the next steps of installation.
  2. Install Boost C/C++ library, Python, and the Eigen 3 package. Usually, both Boost and Python are installed on most Unix-type systems, in which case you only need to find out where those packages are. Note, that we assume Python 2.* version is in use. Python 3.* family is not tested. Also, refer to this page, to find out more on how to build Boost.Python and other Boost libraries from the source code.
  3. Edit your CMakeLists.txt file. Below, we refer to this particular example:
    • Set your version of Boost: e.g. lines 35 and 42 request the 1.50.0 version of Boost
    • Set your version of Python: e.g. line 53 requests the 2.6.8 version of Python. Also note that "EXACT" keyword is supplied in the FIND_PACKAGE function. Normally, you wouldn't want that option (so delete it). This is mostly for the cmake to find the correct version of Python installed on my cygwin system. Well, as you can guess from the lines 51-52 and 58-59, I had a difficulty cmake finding the correct packages. In that case you would need to use "dirty" manual way of defining environment variables before you can compile Libra. Namely, in my case the libraries (python.2.6.exe and libpython.2.6.dll) are located in /home/Alexey_2/Soft/python2.6/bin , whereas the include files (such as Python.h ans bunch of other files) are located in /home/Alexey_2/Soft/python2.6/include/python2.6 So, for the cmake to generate a proper Makefile, i would need to call cmake with the corresponding arguments:
      cmake -DPYTHON_INCLUDE_DIR=/home/Alexey_2/Soft/python2.6/include/python2.6 -DPYTHON_LIBRARY=/home/Alexey_2/Soft/python2.6/bin ../ (see about this below). The same situation applies to Boost libraries and include files.
    • Make the selection of definitions, depending on your platform (lines 68-69). The default choice is good for cygwin. That is why the line 68 is commented, and the line 69 defines the CYGWIN variable via ADD_DEFINITIONS. If you are on the Unix machine - comment this line and uncomment the line 68. In later versions, i'll try to make this determination automatic.
    • Setup the include dir for Eigen library. I know, that is not very convenient, and i hope to fix this at some point, but here is how it is done now. The Eigen3 package is nice in the sense that it is fully template-based. So, one doesn't need to compile it - nice, isn't it? Thus, the installation of Eigen3 reduces to unpacking the distibutive and setting up the environment variable. Eigen 3 is needed for compiling libmeigen library, so we need to edit one of the internal CMakeLists.txt files - here. In this script this is done via set(EIGEN_INCLUDE /home/Alexey_2/Soft/eigen-eigen-2249f9c22fe8/) (line 6). The include directory is the one that contains the "Eigen" directory. In my case that is the /home/Alexey_2/Soft/eigen-eigen-2249f9c22fe8/
  4. Now, we are ready to configure the package. But first, lets create the folder that will contain all the compiled object files and binaries, as well as final libraries. In case you screw up something, you can just delete the whole directory, create a new one, and rebuild the code again. Well, this is pretty standard practice when working with cmake. In my case, i create the folder "_build", in the package directory (the outermost folder "libracode"), so that "libracode/src", "libracode/tests", and "libracode/_build" are all siblings. Creating: [alexeyak@ccr...]mkdir _build
    Once the directory is created, switch to that directory: [alexeyak@ccr...]cd _build
    From there, run the cmake, to create and configure the Makefile file: [alexeyak@ccr...]cmake ../
    Here we refer to the upper level directory that contains "CMakeLists.txt" file. Also, recall that if you need to manually specify the location of include and library files for Python or Boost, you can do it at this point - see the example above.
  5. Compile the code. Once the configuration and build are done, we can compile and build the Libra package. If the configuration is successfull, the Makefile will be created in the "_build" directory. So, we are good to: [alexeyak@ccr...]make
  6. Copy Python files included in the Libra code. These files are located in the "src/libra_py" directory of the source code. The files are not copied when the code is compiled and build. Well, for sure this doesn't happen when no updates of the core components made, but may happen when the components are built for the first time. So, to be safe (and absolutely necessary when you update Python scripts in the "src/libra_py"!!!) one needs to build a specific target. Assuming you are still in the "_build" directory, do:

    cmake ../
    make copy-libra-py
    		  

    This will simply copy the Python scripts from the source directory to the build directory. So, eventually, one would need to add only the latter to the PYTHONPATH and LD_LIBRARY_PATH

  7. Formal installation. Once the binary libraries are created, they together with the include files must be placed into a special place. This is what cmake installer does. But at this point, i haven't get to this point yet. So, we can consider our installation finished. The only effect of this will be in the need to add the location of the called libraries to the Python path, but this can be easily done in the Python scripts, as will be shown later.

    Update (as of 4/10/2016):

    The libra package is now updated to produce a single module called "libra_core", which can be called by

    import liblibra_core
    on Linux OS and
    import cyglibra_core
    on Cygwin

    This will enable utilization of all exported C++ functionality without the need to import each individual module. In order for the above import functions work, we, of course, need to add the path to the folder containing liblibra_core or cyglibra_core binaries to the PYTHONPATH and LD_LIBRARY_PATH:

    export PYTHONPATH=/home/Alexey_2/Programming/Project_libra/_build/src:$PYTHONPATH
    export LD_LIBRARY_PATH=/home/Alexey_2/Programming/Project_libra/_build/src:$LD_LIBRARY_PATH