qmckl/tools/Building.org

#+TITLE: Building tools

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

* Helper functions
 #+NAME: header
 #+begin_src sh :tangle no :exports none :output none
echo "This file was created by tools/Building.org"
 #+end_src

  #+NAME: check-src
  #+begin_src bash
if [[ $(basename ${PWD}) != "src" ]] ; then
    echo "This script needs to be run in the src directory"
    exit -1
fi
  #+end_src

  #+NAME: url-issues
  : https://github.com/trex-coe/qmckl/issues

  #+NAME: url-web
  : https://trex-coe.github.io/qmckl

  #+NAME: license
  #+begin_example
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.

  #+end_example

* Makefile
  :PROPERTIES:
  :header-args: :tangle ../src/Makefile :noweb yes :comments org
  :END:

  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.
** Header                                                          :noexport:

 #+begin_src makefile
# <<header()>>
 #+end_src
** Dependencies

   #+begin_src makefile
LIBS=-lpthread
   #+end_src

** Variables

   #+begin_src makefile
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/
   #+end_src

** Compiler options

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

 #+begin_src makefile
COMPILER=GNU
#COMPILER=INTEL
#COMPILER=LLVM
 #+end_src

*** GNU

    #+begin_src makefile
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
    #+end_src

*** Intel

    #+begin_src makefile
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
    #+end_src

*** LLVM

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

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

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

** Rules

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

   #+begin_src makefile
.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/build_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
   #+end_src

* Script to tangle the org-mode files
  :PROPERTIES:
  :header-args: :tangle tangle.sh :noweb  yes :shebang #!/bin/bash :comments org
  :END:

  #+begin_src bash
# <<header()>>

<<check_src>>
  #+end_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.

  #+begin_src bash
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
  #+end_src

* Script to generate auto-generated Makefile
  :PROPERTIES:
  :header-args: :tangle create_makefile.sh :noweb  yes :shebang #!/bin/bash :comments org
  :END:

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

  #+begin_src bash
# <<header()>>

<<check_src>>

OUTPUT=Makefile.generated
  #+end_src

  We start by tangling all the org-mode files.

  #+begin_src bash
${QMCKL_ROOT}/tools/tangle.sh *.org
  #+end_src

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

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

  for tests in C:

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

  and for tests in Fortran:

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

  Finally, we append the rules to the Makefile

  #+begin_src bash
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

  #+end_src

* Script to build the final qmckl.h file
  :PROPERTIES:
  :header-args:bash: :tangle build_qmckl_h.sh :noweb  yes :shebang #!/bin/bash :comments org
  :END:

  #+begin_src bash :noweb yes
# <<header()>>

  #+end_src

  #+NAME: qmckl-header
  #+begin_src text :noweb yes
------------------------------------------
 QMCkl - Quantum Monte Carlo kernel library
 ------------------------------------------

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

 <<license()>>


  #+end_src

  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:

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

  Generate C header file

  #+begin_src bash
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
  #+end_src

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

  #+begin_src bash
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
  #+end_src

* Script to build the documentation
  :PROPERTIES:
  :header-args:bash: :tangle build_doc.sh :noweb  yes :shebang #!/bin/bash :comments org
  :END:

  First define readonly global variables.
  
  #+begin_src bash :noweb yes
readonly DOCS=${QMCKL_ROOT}/docs/
readonly SRC=${QMCKL_ROOT}/src/
readonly HTMLIZE=${DOCS}/htmlize.el
readonly CONFIG_DOC=${QMCKL_ROOT}/tools/config_doc.el  
readonly CONFIG_TANGLE=${QMCKL_ROOT}/tools/config_tangle.el  
  #+end_src

  Check that all the defined global variables correspond to files.

  #+begin_src bash :noweb yes
function check_preconditions()
{
    if [[ -z ${QMCKL_ROOT} ]]
    then
        print "QMCKL_ROOT is not defined"
        exit 1
    fi

    for dir in ${DOCS} ${SRC}
    do
        if [[ ! -d ${dir} ]]
        then
            print "${dir} not found"
            exit 2
        fi
    done
    
    for file in ${CONFIG_DOC} ${CONFIG_TANGLE}
    do
        if [[ ! -f ${file} ]]
        then
            print "${file} not found"
            exit 3
        fi
    done
}
  #+end_src

 ~install_htmlize~ installs the htmlize Emacs plugin if the
 =htmlize.el= file is not present.

  #+begin_src bash :noweb yes
function install_htmlize()
{
    local url="https://github.com/hniksic/emacs-htmlize"
    local repo="emacs-htmlize"
    
    [[ -f ${HTMLIZE} ]] || (
        cd ${DOCS}
        git clone ${url} \
            && cp ${repo}/htmlize.el ${HTMLIZE} \
            && rm -rf ${repo}
        cd -
    )

    # Assert htmlize is installed
    [[ -f ${HTMLIZE} ]] \
        || exit 1
}
  #+end_src

  Extract documentation from an org-mode file.

  #+begin_src bash :noweb yes
function extract_doc()
{
    local org=$1
    local local_html=${SRC}/${org%.org}.html 
    local html=${DOCS}/${org%.org}.html 

    if [[ -f ${html} && ${org} -ot ${html} ]]
    then
        return
    fi
    emacs --batch                    \
          --load ${HTMLIZE}          \
          --load ${CONFIG_DOC}       \
          ${org}                     \
          --load ${CONFIG_TANGLE}    \
          -f org-html-export-to-html 
    mv ${local_html} ${DOCS}

}
  #+end_src

  The main function of the script.
  
  #+begin_src bash :noweb yes
function main() {
    
    [[ check_preconditions ]] \
        || exit 1
    
    # Install htmlize if needed
    [[ install_htmlize ]] \
        || exit 2

    # Create documentation
    cd ${SRC} \
        || exit 3

    for i in *.org
    do
        echo
        echo "=======  ${i} ======="
        extract_doc ${i}
    done

    if [[ $? -eq 0 ]]
    then
        cd ${DOCS}
        rm -f index.html
        ln README.html index.html
        exit 0
    else
        exit 3
    fi
}
main
  #+end_src