Skip to content

Latest commit

 

History

History
312 lines (230 loc) · 12.1 KB

README.md

File metadata and controls

312 lines (230 loc) · 12.1 KB

LaGriT and ExodusII with cmake

The CMake build system is a way of enabling LaGriT to be cross-platform, cross-architecture, and cross-compiler. This page is a verbose description of building LaGriT and includes instructions for building the optional library for ExodusII.

The CMake build is controlled by CMakeLists.txt and files in directory /cmake

The ExodusII libraries can be built using install-exodus.sh or MAC_install-exodus.sh For additional help on ExodusII, see instructions at https://github.com/sandialabs/seacas Note for Exodus with LaGriT, FORTRAN must be set to YES

There's a really good tutorial-overview on CMake here, it covers how to handle multiple build configurations: https://cliutils.gitlab.io/modern-cmake/

Download LaGriT

Download the repo as shown under the Code button on git. For developers, be sure to use SSH version to clone.

$ git clone [email protected]:lanl/LaGriT.git 
$ cd LaGriT/

If SSH Key needed, generate a key for your machine. See GitHub Docs for SSH Key

Generate a SSH key (NOT RSA) in your .ssh directory.
ssh-keygen -t ed25519 -C "email.lanl.gov"
Copy contents of id_ed25519.pub into your SSH Keys on github (under settings).

Build With ExodusII (optional)

From the top directory run: ./install-exodus.sh or for a mac use: ./MAC_install-exodus.sh The script will take some time to clone, configure, and build the necessary lib and include files. Read comments in the script for hints if things go wrong. For additional help on ExodusII, see instructions at https://github.com/sandialabs/seacas

LaGriT requires the following:

/seacas/lib/ libexodus.a  libexodus_for.a  libexoIIv2for32.a
/seacas/include/ exodus_config.h  exodusII.h  exodusII.inc  exodusII_int.h  exodusII_par.h

Once the ExodusII is successful, build LaGriT as usual using the EXODUS flag:

mkdir build/ && cd build/
cmake .. -DLAGRIT_BUILD_EXODUS=ON
make

Build Without ExodusII

If you do not need to write an Exodus formatted file, you can build LaGriT without the ExodusII libraries. Create a directory for your lagrit executable, then use cmake to create the configuration files and directories.

From the top directory in LaGriT:

mkdir build
cd build
cmake ..

Cmake will use settings defined in LaGriT/CMakeLists.txt and should look something like this:

-- ==========================================
-- ============Configuring LaGriT============
-- ===================v3.3.3=================
-- Compile LaGriT as a static binary = ON
-- Compile LaGriT with ExodusII = OFF
LaGriT Compiling without ExodusII support.
To include Exodus, use -DLAGRIT_BUILD_EXODUS=ON
-- Detecting LaGriT build using local cmake files:
--   Operating System: Linux
--   Architecture: 64-bit
--   Fortran compiler: GNU GFORTRAN
--   C compiler: GNU GCC
--   C++ compiler: GNU G++
-- Configuring done
-- Generating done
-- Build files have been written to: /project/eesdev/tam/clone/LaGriT/build

Once cmake has configured the directory files, type make to compile the lagrit executable:

make

This directory will create the lagrit executable using the files created by cmake.

Scanning dependencies of target liblagrit
[  0%] Building Fortran object CMakeFiles/liblagrit.dir/src/ColoredGraphModule.f90.o
...
[100%] Built target liblagrit
Scanning dependencies of target lagrit
[100%] Building Fortran object CMakeFiles/lagrit.dir/src/lagrit_main.f.o
[100%] Linking Fortran executable lagrit
[100%] Built target lagrit

Run LaGriT Test Suite

Go to LaGriT/test and run the test script. See the README file for further instructions.

$ cd test
$ python runtests.py

Create your build directory:

By default, most the scripts will expect the lagrit executable to be in the "build" directory. But you build in directories with other names. You can build as Debug (-g) or as Release with the CMake flag "-D CMAKE_BUILD_TYPE=[Debug|Release]". There's two stages in CMake; the 'configure' stage (where you run 'cmake ..') and the build stage (where you run 'make' using the Makefile created by cmake)

The build type can only be set in the configure stage (with cmake) and will apply to all files in your build directory. If you make a change to cmake, you will need to run in a new directory, or remove all the files and directories created with your previous cmake configuration.

Setup a work directory for dev and debug work (example using name "debug"). Use cmake to create Makefiles and build files. You will do this only once. Compile the lagrit executable using 'make' or 'make VERBOSE=1'

mkdir debug && cd debug
cmake .. -D CMAKE_BUILD_TYPE=Debug
make

Run ./lagrit and type command test which creates hex mesh and reports expected values.

For debugging the build process, set cmake and make to show verbose screen reporting. These are run from your build directory with the following options:

cmake -D CMAKE_FIND_DEBUG_MODE=ON ..
make VERBOSE=1

Modify code and update lagrit executable

Modify code by working with lagrit source files in LaGriT/src Do not add any non-code develpment files in the /src directory, they may be detected and attempted to use during compile time.

When you want to compile, do not run cmake again, it already created your makefiles, .o, and other dependencies.

Go to LaGriT/your_build_name directory and type

make

lagrit will be built in LaGriT/your_build_name directory.

If you add new files to /src you will need to run cmake again. This will detect all files in src/ and create a new set of Makefiles.

Example Directory structure for developers:

LaGriT/
|
└── build/
    └── lagrit executable, Makefiles built by cmake, cmake files    
└── src/
    └── file.cpp, file.f, file.c, lagrit.h, etc
|
├── CMakeLists.txt
└── cmake/
    └── CompilerFlags-C.cmake, CompilerFlags-Fortran.cmake, DetectBitSize.cmake, PlatformSettings.cmake

Example Screen Output for cmake .. -DLAGRIT_BUILD_EXODUS=ON

-- The Fortran compiler identification is GNU 7.5.0
-- The CXX compiler identification is GNU 7.5.0
-- The C compiler identification is GNU 7.5.0
-- ==========================================
-- ============Configuring LaGriT============
-- ===================v3.3.3=================
-- Compile LaGriT as a static binary = ON
-- Compile LaGriT with ExodusII = ON
-- ExodusII libraries      : /project/eesdev/tam/LaGriT/TPLs/seacas/lib
-- ExodusII include        : /project/eesdev/tam/LaGriT/TPLs/seacas/include
-- Detected System:
--   Operating System: Linux
--   Architecture: 64-bit
--   Fortran compiler: GNU GFORTRAN
--   C compiler: GNU GCC
--   C++ compiler: GNU G++
-- Using Third Party Libraries.
-- TPL libs: /project/eesdev/tam/LaGriT/TPLs/seacas/lib
-- TPL include: /project/eesdev/tam/LaGriT/TPLs/seacas/include
-- Detecting Fortran/C Interface - Found GLOBAL and MODULE mangling
-- Verifying Fortran/C Compiler Compatibility - Success
-- Compilers:
--   FORTRAN [compiler = "/usr/bin/f95"; flags = " -m64 -fcray-pointer -fdefault-integer-8 -std=legacy -fno-sign-zero -fno-range-check"]
--   C [compiler = "/usr/bin/cc"; flags = " -w -m64"]
--   C++ [compiler = "/usr/bin/c++"; flags = " -w -m64"]
-- Configuring done
-- Generating done
-- Build files have been written to: /project/eesdev/tam/LaGriT/build

Example Screen Output for make VERBOSE=1

[  2%] Building C object CMakeFiles/liblagrit.dir/lg_util/src/gmvwrite.c.o
/usr/bin/cc -DLAGRIT_INCLUDE_EXODUSII -Dlinx64 -I/project/eesdev/tam/LaGriT/TPLs/seacas/include -w -m64 -MD -MT CMakeFiles/liblagrit.dir/lg_util/src/gmvwrite.c.o -MF CMakeFiles/liblagrit.dir/lg_util/src/gmvwrite.c.o.d -o CMakeFiles/liblagrit.dir/lg_util/src/gmvwrite.c.o -c /project/eesdev/tam/LaGriT/lg_util/src/gmvwrite.c

[ 36%] Building Fortran object CMakeFiles/liblagrit.dir/src/dumpexodusII.f.o
/usr/bin/f95 -DLAGRIT_INCLUDE_EXODUSII -Dlinx64 -I/project/eesdev/tam/LaGriT/TPLs/seacas/include -m64 -fcray-pointer -fdefault-integer-8 -std=legacy -fno-sign-zero -fno-range-check -cpp -c /project/eesdev/tam/LaGriT/src/dumpexodusII.f -o CMakeFiles/liblagrit.dir/src/dumpexodusII.f.o

[ 70%] Building CXX object CMakeFiles/liblagrit.dir/src/poi_helperFunctions.cpp.o
/usr/bin/c++ -DLAGRIT_INCLUDE_EXODUSII -Dlinx64 -I/project/eesdev/tam/LaGriT/TPLs/seacas/include -w -m64 -MD -MT CMakeFiles/liblagrit.dir/src/poi_helperFunctions.cpp.o -MF CMakeFiles/liblagrit.dir/src/poi_helperFunctions.cpp.o.d -o CMakeFiles/liblagrit.dir/src/poi_helperFunctions.cpp.o -c /project/eesdev/tam/LaGriT/src/poi_helperFunctions.cpp

[100%] Linking CXX static library liblagrit.a
/n/swdev/packages/Ubuntu-18.04-x86_64/cmake/cmake-3.22.1/bin/cmake -P CMakeFiles/liblagrit.dir/cmake_clean_target.cmake

/n/swdev/packages/Ubuntu-18.04-x86_64/cmake/cmake-3.22.1/bin/cmake -E cmake_link_script CMakeFiles/liblagrit.dir/link.txt

/usr/bin/ranlib liblagrit.a
make[2]: Leaving directory '/project/eesdev/tam/LaGriT/build'
[100%] Built target liblagrit

[100%] Linking Fortran executable lagrit
/n/swdev/packages/Ubuntu-18.04-x86_64/cmake/cmake-3.22.1/bin/cmake -E cmake_link_script CMakeFiles/lagrit.exe.dir/link.txt

/usr/bin/f95 -static-libgcc -static-libstdc++  -m64 -fcray-pointer -fdefault-integer-8 -std=legacy -fno-sign-zero -fno-range-check CMakeFiles/lagrit.exe.dir/src/lagrit_main.f.o -o lagrit  liblagrit.a -L/project/eesdev/tam/LaGriT/TPLs/seacas/lib -lexodus_for -lexodus -lnetcdf -lhdf5_hl -lhdf5 -lz -ldl -static-libgfortran -static-libgcc -lstdc++ 

[100%] Built target lagrit

Automatic Configurations

This is work performed by cmake and is usually not modified. Cmake is used to do some automatic file edits that depend on the machine or platform you are using.

Header File configuration

CMake automatically configures two header files:

  • lg_util/src/mm2000.h
  • src/lagrit.h

The original files have the same name, but ending with .in.

CMake configures the files as following. Consider a line from lagrit.h.in:

      parameter      (v_major=@PROJECT_VERSION_MAJOR@)

Here, @PROJECT_VERSION_MAJOR@ is a CMake variable which will be replaced by CMake.

Here is how CMake configures the file:

configure_file(
    ${SRC_CORE}/lagrit.h.in
    ${SRC_CORE}/lagrit.h
    @ONLY
)

${SRC_CORE}/lagrit.h.in is the 'template' file, and ${SRC_CORE}/lagrit.h is the output file. The @ONLY line means to only replace variables between the @ symbol.

The variable above - @PROJECT_VERSION_MAJOR@ is an instrinsic CMake variable. You can define your own. For example, CMake code within SetBitSize.cmake configures the lg_util/src/mm2000.h.in file.

C-Fortran Compatibility

LaGriT codes include both Fortran and C/C++ code files. The driver routines are Fortran, the C/C++ files use wrapper functions and definitions set by cmake before code is compiled. These are set during the configuration and should not need to be modified unless new routines are added.

cmake writes fc_mangle.h for c-fortran routines. This file handles the symbol mangling for routines declared in src/lg_f_interface.h include file. For more information on this method visit https://www.netlib.org/lapack/lawnspdf/lawn270.pdf

The C++ wrapper routines need to be listed in CMakeLists.txt:

FortranCInterface_HEADER(
    ${SRC_CORE}/fc_mangle.h
    SYMBOLS
        INITLAGRIT # syntax: <subroutine>
        DOTASK
        CMO_GET_NAME
        CMO_GET_INFO
        CMO_GET_INTINFO
        FC_CMO_GET_INT
        FC_CMO_GET_VINT
        FC_CMO_GET_DOUBLE
        FC_CMO_GET_VDOUBLE
        FPASS_TYPES
        INSIDE_TET
        LINESEG_TRI)

LaGriT command TEST

The following commands have been added as tests during execution. These are especially useful in testing and to debug the c-fortran codes on various machines.

test (no second word) - easy test using createpts to check executable
test list - list available options
cpp -  call dotask and c-fortran wrappers using get_info calls to get pointers from fortran
fortran - call dotask and get_info pointers used by cpp
dotask - call dotask_test which avoids global commands and just tests dotask parameters