Getting Started

This tutorial shows you how you can call LehrFEM++ from your own code in a few simple steps. We will make a very simple program that calls LehrFEM++ and prints the number of nodes of a triangle to the console.

Note

Because LehrFEM++ relies on the Hunter Package Manager, there is no need to download LehrFEM++ itself!

1. Check Prerequisites

You only need a recent version of CMake (>= 3.10) and one of the supported compilers:

• Linux:
  • Clang Version >= 17 (tests run with clang-17)
  • GCC Version >= 13 (tests run with g++-13)
• OSX:
  • XCode >= 14.2, respectively macos 12.7.2 (tests run with XCode 14.2)
• Windows:
  • Visual Studio 2022 (Version 17.8) or later is required (tests run with VS2022), only x64 is supported!

2. Create a new CMake project

1. Create a folder getting_started somewhere on your system and create the subfolder cmake in it, e.g.

   > mkdir getting_started
   > cd getting_started
   > mkdir cmake

2. Create the empty file getting_started/main.cc. Later on, we will add the main() function to this file and call LehrFEM++ from there.
3. Download the HunterGate.cmake file into getting_started/cmake

   > cd cmake
   > wget https://raw.githubusercontent.com/cpp-pm/gate/master/cmake/HunterGate.cmake

   On Mac OSX use curl instead:

   > cd cmake
   > curl -O https://raw.githubusercontent.com/cpp-pm/gate/master/cmake/HunterGate.cmake

   This file is needed to setup the hunter package manager (which runs completly inside CMake).
4. Create the file getting_started/CMakeLists.txt with the following content

   cmake_minimum_required(VERSION 3.10)
    
   ### Hunter package manager ###
   include("cmake/HunterGate.cmake")
   HunterGate(
       URL "https://github.com/cpp-pm/hunter/archive/v0.25.3.tar.gz"
       SHA1 "0dfbc2cb5c4cf7e83533733bdfd2125ff96680cb"
   )
    
   ### Setup CMake Project ###
   project(GettingStarted)
    
   # download dependencies
   hunter_add_package(lehrfempp)
   find_package(lehrfempp CONFIG REQUIRED)
    
   # define executable
   add_executable(getting_started main.cc)
    
   # link executable with LehrFEM++ module lf::base
   target_link_libraries(getting_started LF::lf.base) 

   Note that this CMakeLists.txt links only with the lf.base module of LehrFEM++. Because we only want to print the number of nodes of a triangle, it suffices to link to the lf.base module. However, if you want to use more functionality, you will probably need to link to other LehrFEM++ modules as well. See Modules for more info about LehrFEM++ modules and list of namespaces for a list of all LehrFEM++ modules.
5. Your folder structure should look as follows:

   getting_started
   +-- CMakeLists.txt
   +-- main.cc
   +-- cmake
   |   +-- HunterGate.cmake

6. Use CMake to create the makefiles for you. Depending on your platform, you have a few different options. It is strongly suggested that you do an out-of-source build, i.e. that you place your binaries in a folder that is different from getting_started. E.g. on linux:

   > cd getting_started
   > mkdir bin
   > cd bin
   > cmake .. 

   The first time you run CMake, it will take a while because hunter will download all dependencies (LehrFEM++ and its dependencies) and compile them.

3. Write a program

Here we will write a very simple program that prints the number of nodes of a triangle to the console. For this we write the following code into the previously created main.cc:

#include <iostream>
 
// Include the lf::base module
#include <lf/base/base.h>
 
 
int main() {
  std::cout << lf::base::RefEl::kTria().NumNodes() << std::endl;
  return 0;
}

Afterwards compile your program and run it. Example on linux:

> cd getting_started/bin
> make
> ./getting_started

Notes about versioning

The LehrFEM++ team releases new versions of LehrFEM++ on hunter when important changes happen. These releases are tagged on github and you can see all releases here.

It's important to understand that the concrete HunterGate command that you use in your CMakeLists will determine the versions of LehrFEM++ that you can use in your code. If you want to use the latest version of LehrFEM++, you should also use the latest HunterGate command. Hunter allows you to select the LehrFEM++ version explictly, see here. If you don't specify a version explicitly, the most recent version which is available with your current HunterGate command, is used.

Use a cutting edge version of LehrFEM++

Hunter also allows you to manually use any commit from the LehrFEM++ github repository. This can be useful if you want to use a version of LehrFEM++ that has not yet been officially released via hunter. We show here how you can use the commit with hash 41fe4560d5f56612059c3f919ec1a83093116984 in your own project.

1) Determine the SHA1 hash of the commit:

wget https://github.com/craffael/lehrfempp/archive/41fe4560d5f56612059c3f919ec1a83093116984.tar.gz
openssl sha1 41fe4560d5f56612059c3f919ec1a83093116984.tar.gz

2) create the file cmake/Hunter/config.cmake in your own project and fill it with the following content (see here for more information), adapt it accordingly if you want to use another commit(!):

hunter_config(lehrfempp
  URL "https://github.com/craffael/lehrfempp/archive/41fe4560d5f56612059c3f919ec1a83093116984.tar.gz"
  SHA1 "096b893adecebe22b57fe5677e7edb0887b2cecc"
)

3) modify the HunterGate command in your top-level CMakeLists.txt so that it includes the local config file:

HunterGate(
    URL ...
    SHA1 ...
    LOCAL # use cmake/Hunter/config.cmake
)

4) build your project as before. Note that the commit that the build can fail depending on whether the commit you have selected built LehrFEM++ correctly.