Use_ALPGraphBLAS_in_your_own_project.md

  Copyright 2021 Huawei Technologies Co., Ltd.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

How-To use ALP/GraphBLAS in your own project

This guide explains how to import ALP/GraphBLAS as a dependency inside a user-written application. As usual, the first step is to perform compilation and installation of ALP/GraphBLAS, as described in the main README. To summarise (also with distributed backends)

mkdir build
cd build
../bootstrap.sh --prefix=</path/to/install/dir> --with-lpf=</path/to/lpf/installation/>
make -j install

After installation, there are two ways to import ALP/GraphBLAS into your application. The first way is to use the provided wrapper scripts to compile your application, while the second way is to import ALP/GraphBLAS as a CMake target via CMake itself.

The following sections explain each strategy.

Via the Wrapper Scripts

This way consists in invoking certain scripts generated during installation that essentially wrap ALP/GraphBLAS compiler and add the relevant options for the chosen backend. These are the scripts used in the Compilation example of the main README. This way is more suitable for small prototype applications, for example compiled via a simple Bash command or a Makefile. You may compile your application by calling the grbcxx C++ compiler wrapper located inside the install path, at </path/to/install/dir>/bin, and by passing it the backend name after the --backend switch, as in

</path/to/install/dir>/bin/grbcxx --backend bsp1d my_app.cpp -o my_app_exe -Wall -Wextra -I<my_include_folder> ...

the wrapper translates the option -backend bsp1d into the proper compiler flags, adds all the other wrapper's arguments straight away and calls the compiler. To inspect the compiler command withouth running it, the option --show can be added. Similarly, the grbrun script is available in the same folder of grbcxx to run the generated binary according to the backend, for example

</path/to/install/dir>/bin/grbrun --backend bsp1d my_app.cpp

Here too the option --show is available to inspect the command without running it.

Finally, the user may add the aforementioned scripts with the related options to her Bash environment by sourcing the setenv file in the same directory, as

source </path/to/install/dir>/bin/setenv

so as to avoid typing their path each time. The script also defines some convenient environment variable, like the list of available backends and the LPF runner path.

The interested user can understand how these wrappers are generated by inspecting the src/CMakeLists.txt file. Note that they invoke the same C++ compiler used for the ALP/GraphBLAS build, to avoid issues due to name mangling and namespace aliasing.

Via CMake

The most structured way to add ALP/GraphBLAS to your own project is via CMake. Indeed, on installation ALP/GraphBLAS generates a CMake infrastructure for consuming projects to import the backend targets and the related dependencies. This infrastructure is stored inside the installation directory and can be inspected at </path/to/install/dir>/cmake.

To import ALP/GraphBLAS into you own project, it suffices to add the ALP/GraphBLAS installation path to your project's CMakeLists.txt root file, together with the standard find_package() call for CMake to discover the configuration files. Hence, an example CMakeLists.txt for your project is

cmake_minimum_required( VERSION 3.13 )

project( example LANGUAGES CXX )
set( CMAKE_CXX_STANDARD 11 )
set( CMAKE_CXX_STANDARD_REQUIRED ON )

option( GRB_PATH "Path to ALP/GraphBLAS" )

find_package( ALPGraphBLAS # fixed name for the CMake config packaged: do not change!
  REQUIRED                 # if not found, raise an error
  CONFIG                   # search for the CMake configuration files
  PATHS "${GRB_PATH}"      # search inside "${GRB_PATH}"
)
message( STATUS "available backends: ${ALPGraphBLAS_AVAILABLE_BACKENDS}" ) # variable automatically added during find_package() call

add_executable( my_app_exe my_app.cpp )
target_link_libraries( my_app_exe ALPGraphBLAS::backend_hybrid_static )

which

1. imports ALP/GraphBLAS via its CMake infrastructure via find_package( ALPGraphBLAS ... )
2. prints the available backends via message( STATUS "available backends: ${ALPGraphBLAS_AVAILABLE_BACKENDS}" )
3. creates an executable named my_app_exe from the source file my_app.cpp via add_executable( my_app_exe my_app.cpp )
4. links the my_app_exe target to the hybrid static backend via target_link_libraries( my_app_exe ALPGraphBLAS::backend_hybrid_static )

From this example you may notice that the targets referring to the backends live in the ALPGraphBLAS:: namespace and have the same naming as in the conventions

When invoking cmake to build the project's compilation infrastructure, the option GRB_PATH should be set to the usual </path/to/install/dir>, as in

mkdir my_app_build
cd my_app_build
cmake -DGRB_PATH=</path/to/install/dir> ../
make my_app_exe

The -DGRB_PATH=</path/to/install/dir> argument does not contain any sub-directory, since the find_package( ... CONFIG ... ) call automatically takes care of searching for the appropriate CMake files within, according to the Config Mode Search Procedure.

In the case of the executable my_app_exe linked to the hybrid backend, you can run it via the lpfrun utility in the LPF installation directory, as from the main README.

As a note for developers, the CMake import infrastructure is generated throughout the creation of the various targets in the ALP/GraphBLAS CMake infrastructure via the install( TARGETS <target names> EXPORT GraphBLASTargets ) commands.