MAKE_EXP(1)                      RPN UTILITY                       MAKE_EXP(1)
NAME
        make_exp - create a description file for the make utility.

USAGE
        make_exp [-f] [-DEFINE =-Dtoken1[:-Dtoken2] ...] [-MALIB libname]
                 [-COMPILE file_name] [-FFLAGS=flag[:flag] ...]
                 [-CPPFLAGS=flag[:flag] ...] [-CFLAGS=flag[:flag] ...]
                 [-ASFLAGS=flag[:flag} ...]  [-quick] [-+]

        or

        make_exp -h         to obtain the calling sequence.

DESCRIPTION
        NOTE:  It is assumed that the reader is somewhat familiar with the
                 make  utility.
        make_exp is a command  used to create description  files for the  make
utility.  make is a command  generator used to maintain, update, and  generate
groups of source code  files.  The two  description files created by  make_exp
are named  Makefile and  make_cdk.   The  description  files contain  all  the
dependency relations among  all the source files (between *.[fp]tn and  *.cdk,
between *.c  and *.h  and  between *.s  and *.h)  present  in the  RCS  master
directories as well as in the current directory. Makefile contains the list of
all the .cdk files that are  needed by a given .ftn or .ptn file, and all  the
.h files  that are  needed by  a given  .c or  .s file.  As for  make_cdk,  it
contains the list of all .ftn, .ptn files that need a given .cdk file as  well
as a list of all the .c or .s files that require a given .h file.

        When make_exp is  used in the  etagere environment, (environnement  de
travail automatise de  gestion d'experiences avec  RCS) the description  files
created will  contain all  the dependencies  of  all the  files found  in  the
following directories:

        1- the current working directory
        2- the local RCS sub-directory
        3- all the RCS master directories specified in RCSPATH

        A description  file  (Makefile)  created within  the  etagere  context
should not be used  if there is  no active experiment  in the current  working
directory.

        When make_exp is used outside  of the etagere environment, the  search
for dependencies will  be limited to  the current directory  and the RCS  sub-
directory,  unless  the  environment  variable  RCSPATH  has  previously  been
initialized.   In this context, the presence of the -f keyword is  required.

        The description file Makefile is built in such a way that entering the
command:
           make

will display a menu  of all the possible  targets of Makefile.   The user  may
then select a target by giving the number corresponding to his choice.

PERSONAL TARGETS
        In order to add  targets and macros to  Makefile, the user can  create
additional description files called  mes_recettes and/or my_targets which  are
kept in  the  current  working  directory.  Another  description  file  called
.recettes  can  also be  stored in the  RCS sub-directory.   Furthermore,  the
person responsible for the maintenance of a RCS master directory can also keep
a .recettes file in that master  directory.  All these description files  will
be appended  to Makefile  by make_exp  and their  target definitions  will  be
included in the menu displayed when issuing a make command.

        Note that the search for dependencies (and the inclusion of  .recettes
files) is  done in  reversed order:   the  last directory  of the  RCSPATH  is
searched first  and make_exp  proceeds  backwards to  end  the search  in  the
current directory.  Thus, the macro definitions in the files mes_recettes  and
my_targets will override any previous definition in a .recettes file.

        Note also that a .recettes  file is copied to a RCS directory and  not
checked-in via ci.

        To create a personal description file you must:

       1-  enter the name of the target and its components.
       2-  on the  following  line, enter  a  comment briefly  describing  the
           purpose of the target.
       3-  enter the commands to be executed  in order to generate the  target
           from its components.

        NOTES: The comment starts with a sharp sign (#) and is written on one
                line.  To force a line feed in the display of  the comment,
                insert the characters \n. Only one line feed is allowed.

                All the command lines of the target must begin with a tab.

EXAMPLE OF A FILE my_targets
        In this example, we define a  target that will compile all the  source
files { $(FICHIERS) = $(FDECKS) $(CDECKS) $(ASDECKS) $(COMDECKS)  $(HDECKS)}of
all the directories  (current directory  and RCS sub-directory,  plus all  RCS
master directories) and produce an executable file called "absolu".

        Content of my_targets:
           ________________________________________________________
          |                                                        |
          |absolu:  $(FICHIERS) $(OBJECTS)                         |
          |#Compile all files and produce an  executable\nfile\    |
          |called absolu                                           |
          |        f77 -o $@ $(OBJETCS)                            |
          |________________________________________________________|

        When invoking make without a target name, the above target will become
one of the choices  of the target  menu displayed. To  the menu option  absolu
will be associated an execution number.   The screen should look more or  less
like this:

     _____________________________________________________________________
    |                                                                     |
    |                LISTE DES RECETTES DU FICHIER Makefile               |
    |                                                                     |
    | 1- compil      : compiler tous les .ftn modifies...                 |
    | 2- full        : compiler tous les .ftn ...                         |
    |     .                                                               |
    |     .                                                               |
    |     .                                                               |
    | 15-absolu      : Compile all files and produce an executable        |
    |                  file called absolu                                 |
    |                                                                     |
    |                                                                     |
    |   Entrez q pour terminer                                            |
    |   Entrez le numero de votre choix :                                 |
    |                                                                     |
    |_____________________________________________________________________|

        You may specify, in mes_recettes, my_targets or .recettes, the  number
of menu options displayed per screen by setting the macro NRECETTES:

        NRECETTES = nn

where nn is any number. The default is to display 10 targets per screen.

ARGUMENT DEFINITION
        -f           this keyword  indicates  to  make_exp that  there  is  no
                     current experiment  and that  no RCS  master  directories
                     need to be searched.  This key must be present when using
                     make_exp outside of the etagere environment.

        -DEFINE      this  keyword  indicates  to   make_exp  that  the   next
                     parameter is  a token  to pass  to cpp  when creating  .f
                     files from .ftn or .ptn  files.

                     To generate  a file  aaa.f  from aaa.ftn,  the  following
                     command is issued: 
                          /lib/cpp -P $(DEFINE) aaa.ftn > aaa.f

                     To generate  a file  aaa.f  from aaa.ptn,  the  following
                     command is issued: 
                          /lib/cpp -P $(DEFINE) $(DOC) aaa.ftn | \
                         sed 's/^[ ].*PROGRAM /       SUBROUTINE / \
                         sed 's/^[ ].*program /       subroutine / \ > aaa.f

                     To pass  a  list of  defined  tokens, use  the  following
                     syntax:   -DEFINE =-Dtoken1:-Dtoken2:-Dtoken3

                     Default value: DEFINE='-DNEC=nec'

        -MALIB       the parameter following this keyword  is the name to  use
                     when creating or updating a user library.  The default is
                     to use malib.a as the library name.

                     The $(MALIB) macro is used  by targets:  genlib,  libexp,
                     majlib and qmajlib.

        -COMPILE     the parameter following this keyword  is the name to  use
                     for the file that will contain the collection of .f files
                     generated  by  certain  targets.  By  default,  the  name
                     compile is used.

                     The $(COMPILE) macro is used by targets: compil, qcompil,
                     compexp and full.

        -quick       this  keyword   is  used   to  insert   the  content   of
                     mes_recettes and my_targets  in the  Makefile.   make_exp
                     will not  sort out  the  dependency relations  among  the
                     *.ftn and  *.cdk   files when  this key  is present.  The
                     beginning of Makefile, up to the personal target section,
                     will remain untouched.

                     To modify or add personal targets, the user edits  either
                     mes_recettes   or   my_targets   and   then   issues    a
                     make_exp -quick command  to  insert the  new  targets  in
                     Makefile.

        -FFLAGS      The parameters following this  keyword are flags for  the
                     FORTRAN language compiler f77.

        -CPPFLAGS    The parameters following this  keyword are flags to  pass
                     to the C language preprocessor cpp when producing  object
                     files from C language programs.

        -CFLAGS      The parameters following this keyword are flags for the C
                     language compiler cc.

        -ASFLAGS     The parameters following this  keyword are flags for  the
                     assembly language compiler as.

        -+           This keyword forces  make_exp to  execute in  full-screen
                     mode.

        NOTE:        In order to pass a value containing a negative sign,  the
                     following method must be used:

                               -keyword =-value:-value:-value

                     For example:

                                make_exp -DEFINE=-DUNIX:-Ddebug -FFLAGS=-g:-C

FILES
        Makefile               -description file for .ftn, .ptn, .f, .c and .s
                                files and associated targets.

        make_cdk               -description file for .cdk and .h files.

        arbre_de_dependance    -this file contains a  dependency tree for  all
                                the .ftn, .ptn and .cdk  files as well as  for
                                all .c, .s and  .h files.   This text file  is
                                created and used only  by make_exp. It may  be
                                deleted by  the user  after the  execution  of
                                make_exp.

        .recettes              -personal target files that  reside in the  RCS
                                directories to be searched  by make_exp.   The
                                content of  .recettes  files  is  appended  to
                                Makefile.

        mes_recettes           -personal target files that reside in the
        my_targets              currentworking directory.    The  contents  of
                                mes_recettes and  my_targets are  appended  to
                                Makefile.  my_targets is appended last.

BUGS
        The co-existence of a "deck" and a "comdeck" having the same base name
(ex. aaa.ftn and aaa.cdk or bbb.c  and bbb.h) will cause dependency errors  in
Makefile.

        A target name appearing more than once in Makefile,  will result in an
error message from the menu display program. Refer to the Makefile file before
constructing a personal target file such as mes_recettes.

        The presence of back-up files with  extensions such as .ftn~ or  .ftn#
(emacs back-up files for instance) will cause problems when make_exp generates
the dependency relations between .ftn and .cdk files.

AUTHORS
        J. Caveen, M. Valin, M. Lepine - RPN - April 1991

NOTES
        See also clt_exp(1), cltr_exp(1), dir_exp(1), eff_exp(1),  etagere(1),
frm_exp(1), grep_exp(1),  hst_exp(1), intro_exp(1),  mdm_exp(1),  menu_exp(1),
mrcs_exp(1),     omd_exp(1),     omdr_exp(1),     ouv_exp(1),      qui_exp(1),
rev_exp(1),smod_exp(1) and sor_exp(1).

        See also make(1), cpp(1), ar(1) and cclargs(1).

        Latest revision: November 1993.

                                  APPENDIX 1

LIST OF MACRO DEFINITIONS USED IN Makefile

        DEFINE                  $(DEFINE) contains the list of defined  tokens
                                to pass to cpp (e.g., #if defined  (UNIX))when
                                generating .f files from .ftn or .ptn files.

        FFLAGS                  $(FFLAGS) contains the compilation options  to
                                pass on to the FORTRAN compiler.

        CFLAGS                  $(CFLAGS) contains the compilation options for
                                the C language compiler.

        CPPFLAGS                $(CPPFLAGS) contains the  options for the  cpp
                                pass when  invoking the  C language  compiler.
                                Note that these  options may  be provided  via
                                the CFLAGS macro as well, and vice versa.

        ASFLAGS                 $(ASFLAGS)  contains  the   options  for   the
                                assembly language compiler.

        COMPILE                 $(COMPILE) contains the name of the file which
                                will contain  the  collection of  all  FORTRAN
                                source files produced by certain targets.

        DOC                     $(DOC) may  contains  flags for  cpp  used  to
                                generate documentation files from .ptn  source
                                files.  It is presently set to a null value by
                                make_exp.

        MALIB                   $(MALIB)  contains  the  name  of  the  object
                                library produced  or modified  by the  library
                                generation targets of Makefile.

        RMNLIB                  RMNLIB = $(ARMNLIB)/lib/rmnxlib.a

        FTNDECKS                $(FTNDECKS)  contains the list of all the .ftn
                                files.

        PTNDECKS                $(PTNDECKS)  contains the list of all the .ptn
                                files.

        FDECKS                  $(FDECKS) contains  the  list of  all  the  .f
                                files  (geuine  .f  files  as  well  as  those
                                produced from $(FTNDECKS) and $(PTNDECKS)).

        CDECKS                  $(CDECKS) contains  the  list  of  all  the  C
                                language files.

        ASDECKS                 $(ASDECKS)  contains  the  list  of  all   the
                                assembly language files.

        COMDECKS                $(COMDECKS) contains the list of all the  .cdk
                                files.
        HDECKS                  $(HDECKS) contains  the  list of  all  the  .h
                                files (header files).

        FICHIERS                $(FICHIERS) = $(FDECKS)  $(CDECKS)  $(ASDECKS)
                                              $(HDECKS)

                                  APPENDIX 2

SUFFIXES

        make_exp uses the following rules in the Makefile file:

.SUFFIXES : .ftn .ptn .f .c .s .o

.ptn.o: 
         $(CPP) -P $(DEFINE) $(DOC) $< |\
         sed 's/^[ ].*PROGRAM /       SUBROUTINE /' |\
         sed 's/^[ ].*program /      subroutine /'  > $*.f
         $(FC) $(FFLAGS) -c $*.f
         chmod 444 $*.f

.ptn.f:
         $(CPP) -P $(DEFINE) $(DOC) $< |\
         sed 's/^[ ].*PROGRAM /      SUBROUTINE /' |\
         sed 's/^[ ].*program /      subroutine /'  > $*.f
         chmod 444 $*.f

.ftn.o:
         $(CPP) -P $(DEFINE) $< > $*.f
         $(FC) $(FFLAGS) -c $*.f
         chmod 444 $*.f

.ftn.f:
        $(CPP) -P $(DEFINE) $< > $*.f
        chmod 444 $*.f

.c.o:
        $(CC) -c $(CPPFLAGS) $(CFLAGS) $<

.s.o:
        $(AS) -c $(CPPFLAGS) $(ASFLAGS) $<

                                  APPENDIX 3

LIST OF PREDEFINED TARGETS

NOTE:   in the following descriptions, the term fortran file or .f file refers
        to genuine .f files as  well as those produced  from .ftn and .ptn  as
        indicated in the suffixes rules stated in Appendix 2.

        A .tx t file is a text file such as a shell script that is part of an
        experiment.

obj:    This target will generate object files from all the source code files:
        *.ftn, *.ptn, *.f, *.c, and *.s .

full:   Include all the fortran  files in $(COMPILE) and  fetch all the .c  .s
        and .h files.

compil: Include in  $(COMPILE)  only  the  .f files  affected  by  the  latest
        modifications and fetch all the .c and .s files affected by the latest
        modifications. Note that modifying a .cdk or a .h file will cause  the
        extraction of all the .ftn,  .ptn and .c files  that do a #include  of
        the modified comdeck or header file.

compexp:similar treatment as in the compil  target but performed on the  files
        of the currently open experiment.  This target is reserved to  etagere
        users. Note that this target will extract files with a .txt  extention
        from the RCS working directory if appropriate.

objloc: this target will  generate object files  from the same  set of  source
        code files as in the compil target.

objexp: this target will  generate object files  from the same  set of  source
        code files  as in  the compexp  target.   Note that  this target  will
        extract files with a .txt extention from the RCS working directory  if
        appropriate.

qcompil:include only the modified .f files in the $(COMPILE) file.

qobj:   generate objects files  from the  modified source files.   Unlike  the
        compil target,  qcompil will  not result  in the  extraction of  files
        affected by modifications brought to included files (.cdk and .h).

genlib: create or regenerate  an object library  called $(MALIB)that  includes
        the objects for all the source code files.

majlib: update the object  library $(MALIB)with the  objects generated by  the
        objloc target.

qmajlib:update the object library $(MALIB)  with the objects generated by  the
        qobj target.

libexp: update the object library $(MALIB)  with the objects generated by  the
        objexp target. Note that  this target will extract  files with a  .txt
        extention from the RCS working directory if appropriate.

clean:  remove all unnecessary source code files and remove all object  files.
        This target will not work if you do not own the files or if you invoke
        it while being a substitute user (see su(1) ).

qclean: remove only the .f files that  where produced from .ftn or .ptn  files
        and remove all the  object files.   This target will  not work if  you
        invoke it while being a substitute user (see su(1) ).