qmckl/tools/Building.org

Building tools

• Helper functions
• Makefile
  • Dependencies
  • Variables
  • Compiler options
    • GNU
    • Intel
    • LLVM
  • Rules
• Script to tangle the org-mode files
• Script to generate auto-generated Makefile
• Script to build the final qmckl.h file
• Script to build the documentation
• Script to build the documentation

This file contains all the tools needed to build the QMCkl library.

Helper functions

if [[ $(basename ${PWD}) != "src" ]] ; then
  echo "This script needs to be run in the src directory"
  exit -1
fi

https://github.com/trex-coe/qmckl/issues

https://trex-coe.github.io/qmckl

BSD 3-Clause License

Copyright (c) 2020, TREX Center of Excellence
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
 list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
 this list of conditions and the following disclaimer in the documentation
 and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
 contributors may be used to endorse or promote products derived from
 this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

This is the main Makefile invoked by the make command. The Makefile compiling the library is Makefile.generated, and is generated by the script detailed in the next section.

Dependencies

LIBS=-lpthread

Variables

QMCKL_ROOT=$(shell dirname $(CURDIR))

export CC CFLAGS FC FFLAGS LIBS QMCKL_ROOT

ORG_SOURCE_FILES=$(wildcard *.org)
OBJECT_FILES=$(filter-out $(EXCLUDED_OBJECTS), $(patsubst %.org,%.o,$(ORG_SOURCE_FILES)))
INCLUDE=-I$(QMCKL_ROOT)/include/

Compiler options

GNU, Intel and LLVM compilers are supported. Choose here:

COMPILER=GNU
#COMPILER=INTEL
#COMPILER=LLVM

GNU

ifeq ($(COMPILER),GNU)
#----------------------------------------------------------
CC=gcc -g
CFLAGS=-fPIC  $(INCLUDE) \
-fexceptions -Wall -Werror -Wpedantic -Wextra -fmax-errors=3

FC=gfortran -g
FFLAGS=-fPIC  $(INCLUDE) \
-fcheck=all -Waliasing -Wampersand -Wconversion -Wsurprising \
-Wintrinsics-std -Wno-tabs -Wintrinsic-shadow -Wline-truncation \
-Wreal-q-constant -Wuninitialized  -fbacktrace -finit-real=nan \
-ffpe-trap=zero,overflow,underflow

LIBS+=-lgfortran -lm
#----------------------------------------------------------
endif

Intel

ifeq ($(COMPILER),INTEL)
#----------------------------------------------------------
CC=icc -xHost
CFLAGS=-fPIC -g -O2 $(INCLUDE)

FC=ifort -xHost
FFLAGS=-fPIC -g -O2 $(INCLUDE)

LIBS+=-lm -lifcore -lirc
#----------------------------------------------------------
CC=icc -xHost
endif

LLVM

ifeq ($(COMPILER),LLVM)
#----------------------------------------------------------
CC=clang
CFLAGS=-fPIC -g -O2 $(INCLUDE)

FC=flang
FFLAGS=fPIC -g -O2 $(INCLUDE)

LIBS+=-lm
#----------------------------------------------------------
endif

Rules

The source files are created during the generation of the file Makefile.generated.

.PHONY: clean
.SECONDARY: # Needed to keep the produced C and Fortran files

libqmckl.so: ../include/qmckl.h
$(MAKE) -f Makefile.generated

../include/qmckl.h: Makefile.generated
../tools/build_qmckl_h.sh

test: libqmckl.so
$(MAKE) -f Makefile.generated test

doc: $(ORG_SOURCE_FILES)
$(QMCKL_ROOT)/tools/create_doc.sh

clean:
$(RM)	test_qmckl_* test_qmckl.c test_qmckl \
qmckl_*.f90 qmckl_*.c qmckl_*.o qmckl_*.h \
Makefile.generated libqmckl.so *.html *.mod

Makefile.generated: Makefile $(QMCKL_ROOT)/tools/create_makefile.sh  $(ORG_SOURCE_FILES)
$(QMCKL_ROOT)/tools/create_makefile.sh

Script to tangle the org-mode files

# <<header()>>

<<check_src>>

This file needs to be run from the QMCKL src directory.

It tangles all the files in the directory. It uses the config_tangle.el file, which contains information required to compute the current file names using for example (eval c) to get the name of the produced C file.

The file is not tangled if the last modification date of the org file is less recent than one of the tangled files.

function tangle()
{
  local org_file=$1
  local c_file=${org_file%.org}.c
  local f_file=${org_file%.org}.f90

  if [[ ${org_file} -ot ${c_file} ]] ; then
      return
  elif [[ ${org_file} -ot ${f_file} ]] ; then
      return
  fi
  emacs --batch ${org_file} --load=../tools/config_tangle.el -f org-babel-tangle
}

for i in $@
do
  echo "--- ${i} ----"
  tangle ${i}
done

Script to generate auto-generated Makefile

This script generates the Makefile that compiles the library. The OUTPUT variable contains the name of the generated Makefile,typically Makefile.generated.

# <<header()>>

<<check_src>>

OUTPUT=Makefile.generated

We start by tangling all the org-mode files.

${QMCKL_ROOT}/tools/tangle.sh *.org

Then we create the list of *.o files to be created, for library functions:

OBJECTS="qmckl_f.o"
for i in $(ls qmckl_*.c qmckl_*f.f90) ; do
  FILE=${i%.*}
  OBJECTS+=" ${FILE}.o"
done >> $OUTPUT

for tests in C:

TESTS=""
for i in $(ls test_qmckl_*.c) ; do
  FILE=${i%.c}
  TESTS+=" ${FILE}.o"
done >> $OUTPUT

and for tests in Fortran:

TESTS_F=""
for i in $(ls test_qmckl_*_f.f90) ; do
  FILE=${i%.f90}
  TESTS_F+=" ${FILE}.o"
done >> $OUTPUT

Finally, we append the rules to the Makefile

cat << EOF > ${OUTPUT}
CC=$CC
CFLAGS=$CFLAGS -I../munit/

FC=$FC
FFLAGS=$FFLAGS
OBJECT_FILES=$OBJECTS
TESTS=$TESTS
TESTS_F=$TESTS_F

LIBS=$LIBS

libqmckl.so: \$(OBJECT_FILES)
\$(CC) -shared \$(OBJECT_FILES) -o libqmckl.so

%.o: %.c
\$(CC) \$(CFLAGS) -c \$*.c -o \$*.o

%.o: %.f90 qmckl_f.o
\$(FC) \$(FFLAGS) -c \$*.f90 -o \$*.o

../include/qmckl.h ../include/qmckl_f.f90:
../tools/build_qmckl_h.sh

qmckl_f.o: ../include/qmckl_f.f90
\$(FC) \$(FFLAGS) -c ../include/qmckl_f.f90 -o qmckl_f.o

test_qmckl: test_qmckl.c libqmckl.so \$(TESTS) \$(TESTS_F)
\$(CC) \$(CFLAGS) -Wl,-rpath,$PWD -L. \
../munit/munit.c \$(TESTS) \$(TESTS_F) -lqmckl \$(LIBS) test_qmckl.c -o test_qmckl

test: test_qmckl
./test_qmckl

.PHONY: test
EOF

Script to build the final qmckl.h file

# <<header()>>

------------------------------------------
QMCkl - Quantum Monte Carlo kernel library
------------------------------------------

Documentation : <<url-web()>>
Issues        : <<url-issues()>>

<<license()>>

All the produced header files are concatenated in the qmckl.h file, located in the include directory. The *_private.h files are excluded.

Put .h files in the correct order:

HEADERS=""
for i in $(cat table_of_contents)
do
  HEADERS+="${i%.org}.h "
done

Generate C header file

OUTPUT="../include/qmckl.h"

cat << EOF > ${OUTPUT}
/*
,*    <<qmckl-header>>
,*/

#ifndef __QMCKL_H__
#define __QMCKL_H__

#include <stdlib.h>
#include <stdint.h>
EOF

for i in ${HEADERS}
do
  if [[ -f $i ]] ; then
      cat $i >> ${OUTPUT}
  fi
done

cat << EOF >> ${OUTPUT}
#endif
EOF

Generate Fortran interface file from all qmckl_*_fh.f90 files

HEADERS="qmckl_*_fh.f90"

OUTPUT="../include/qmckl_f.f90"
cat << EOF > ${OUTPUT}
!
!    <<qmckl-header>>
!
module qmckl
use, intrinsic :: iso_c_binding
EOF

for i in ${HEADERS}
do
  cat $i >> ${OUTPUT}
done

cat << EOF >> ${OUTPUT}
end module qmckl
EOF

Script to build the documentation

Script to build the documentation