# |
# o---------------------------------------------------------------------o
# |
# | MAD makefile - documentation
# |
# o---------------------------------------------------------------------o
# |
# | Methodical Accelerator Design
# |
# | Copyright (c) 2011+ CERN, mad@cern.ch
# |
# | For more information, see http://cern.ch/mad
# |
# o---------------------------------------------------------------------o
# |
# | $Id$
# |

The MAD-X makefile is intended to compile project using C, C++ and Fortran 90
compilers in a flexible way. The following sections explain how to configure
the makefile for the project. Changing the value of a variable on the command
line of make allows to setup different configuration for your project, including
the user-defined files included for files selection (see Includes settings).

targets for building the project:
  [none] | $(PROJECT)$(ARCH)$(PROJEXT)

targets for printing information:
  info | infoinc | infoprj | infoall

targets for cleaning generated files:
  clean | cleandir | cleanc | cleancxx | cleanf90 | cleanbuild | cleanall

makefile options:
  - SHOW=yes displays commands executed by make instead of summary message

###################
# Project settings

PROJECT sets the project name.
  The program/library/archive will have the name $(PROJECT)$(ARCH)$(PROJEXT)

Other flags can be added to configure the project.
  Logical flags should use yes/no, not YES/NO

#################
# Build settings

In the following settings, the first option is the default.

ARCH=detect/32/64 sets the target platform archictecture
  'detect' is replaced by 32/64 depending on platform architecture
  The default target will have the name $(PROJECT)$(ARCH)
  The program/library/archive will have the name $(PROJECT)$(ARCH)$(PROJEXT)

DEBUG=yes/no sets/unsets the build for debugging (with dwarf-2 compliance)
  adds -D_DEBUG to CPPFLAGS

PROFILE=yes/no sets/unsets the build for profiling (with gprof compliance)
  adds -D_PROFILE to CPPFLAGS

STATIC=no/yes unsets/sets the build for static linking (for distribution)

PLUGIN=no/yes unsets/sets the build for dynamic loading of plugins
  adds -D_PLUGIN to CPPFLAGS

###################################
# Compilers/Linkers/Tester settings

CC=gcc sets the name of the C compiler.
  The settings of the compiler are included from the file make/compiler.$(CC)

CXX=g++ sets the name of the C++ compiler.
  The settings of the compiler are included from the file make/compiler.$(CXX)

FC=gfortran sets the name of the F90 compiler.
  The settings of the compiler are included from the file make/compiler.$(FC)

LD=ld sets the name of the linker
  The settings of the linker are included from the file make/linker.$(LD)

ND=numdiff sets the name of the tester
  The settings of the tester are included from the file make/tester.$(ND)

Notes:
  - The compiler, linker and tester configuration files are loaded using
    $(makedir)/compiler.$([CC|CXX|FC]NAME)
    $(makedir)/linker.$(LDNAME)
    $(makedir)/tester.$(NDNAME)
    where $([CC|CXX|FC|LD|ND]NAME) are set to $([CC|CXX|FC|LD|ND]) by default.
  - In order to get the list of supported compilers, linkers and testers, do
    ls -l $(makedir)/compiler.*
    ls -l $(makedir)/linker.*
    ls -l $(makedir)/tester.*
    where usually $(makedir)=make.
  - Example:
      make FC=gfortran44 FCNAME=gfortran
    sets the compiler to gfortran44 but uses the configuration of gfortran

####################
# Includes settings

Makefile of the project to include (in this order, all are optional)
  FILE_PRE  contains user's preprocessing extra stuffs
  FILE_VER  contains the project VERSION and VERSION_DATE that must updated
  FILE_CPP  contains extra CPPFLAGS define (-Dname[=value])
  FILE_C    contains C   files selection and sets CC_SRC  and CC_HDR
  FILE_CXX  contains C++ files selection and sets CXX_SRC and CXX_HDR
  FILE_F90  contains F90 files selection and sets FC_SRC
  FILE_LIB  sets LIBS with required paths (i.e. -Lpath) and names (i.e. -llib)
  FILE_SYS  contains system specific stuff (e.g. unsupported configurations)
  FILE_TEST contains project tests
  FILE_POST contains user's postprocessing extra stuffs (e.g. special rules)

Notes:
  - dependencies of C and C++ files are computed automatically if possible
  - dependencies of F90 are computed automatically if possible (often not)
  - dependencies should be provided if resp. CDEP, CXXDEP, FCDEP are empty

####################
# Platform settings

OSTYPE is set to the operating system name 
  One of Linux, Darwin, Cygwin, Windows

OSARCH is set to the operating system architecture
  One of i386, i686, x86, x86_64, amd64, ia64

OBJDIR is set to $(OSTYPE)$(ARCH)
  This is where the files generated by the build (e.g. .o, .d, .mod) are put
  If APPENDLD=yes, then OBJDIR is set to $(OSTYPE)$(ARCH)_$(LDNAME)

NOBUILD is a list of patterns specifying make target which do not make the build.
  It is used to avoid automatic dependencies computation triggered by including
  the .d files (i.e. rules for files dependencies) when they are not required.
 
####################
# Tests settings

TESTS is set to the list of test directories
   tests must be present in the tests subdirectory and prefixed by test-