# ---------------------------------------------------------------------------
#
# Makefile template for a Yorick-based code
#
# $Id: Maketmpl,v 1.1 1993/08/27 18:32:09 munro Exp $
#

# You are trying to build a version of Yorick which includes your own
# compiled routines, which you would like to call from the Yorick
# interpreter just like other built-in functions.  (If you are trying
# to build the original version of Yorick at your site, stop.  You
# should be reading the Makefile.in, not this Maketmpl.)

# ---------------------------------------------------------------------------
# Compiling and Loading your Special Version of Yorick
# ----------------------------------------------------

# The first thing you need to do is to create a directory where you
# can build and debug your special version of Yorick.  I'll call this
# directory Y_BUILD.  Begin by copying this Maketmpl file into your
# Y_BUILD directory.  Change the name of Maketmpl to Makefile.
# Move your source code into the Y_BUILD directory, if it's not there
# already.  You should move anything not related to the one special
# Yorick version you are trying to create out of the Y_BUILD directory
# in order to avoid damaging it.

# This Makefile is divided into two sections:
#   (1) A code specific section, which describes how to compile
#       the modules you are trying to add to Yorick.
#       Modify this section to reflect your code.
#   (2) A site specific section, which parametrizes various
#       compiler switches and options, and provides standard
#       make targets for assembling a complete version of Yorick.
#       DO NOT MODIFY this section if you can avoid it.  (If it
#       needs to be fixed, Maketmpl should be fixed.)

# The idea is that the site specific section represents the
# platform and operating system dependencies which the person
# who built Yorick had to overcome.  If you keep such dependecies
# out of the code specific section, then it will be easy for you
# to port your code to any platform which already has Yorick:
#
#      make Makefile
#
# will replace the site specific section of your Makefile with the
# one it finds in $(Y_HOME)/Maketmpl.
# The only thing you need to find out in order to port your special
# version to a new platform is the Yorick home directory Y_HOME.
# The name of the Y_HOME directory is
#
#     $(exec_prefix)/yorhome
#
# Where exec_prefix varies from installation to installation.  Sibling
# directories bin and lib of yorhome are also significant during the
# building of your code.

# In addition to your Y_BUILD directory, and the public Y_HOME directory,
# you need to be aware of two other directories:
#     Y_SITE    the directory where the machine-independent components
#               of Yorick reside (this may be the same as Y_HOME).
#     Y_LAUNCH  the directory where you put the executable file
#               you are about to build.  (This directory is determined
#               by your version of Yorick when it starts; it may be the
#               same as Y_BUILD.)  If you want to move your version of
#               Yorick to a directory other than Y_BUILD after you
#               have debugged it, see the section "Moving your Special
#               Version of Yorick to Another Directory" below.)
# On my network,
#     Y_HOME = /usr/local/Yorick/1.0/yorhome
#        /usr/local is mounted to one file server of each machine type
#        on the network, so there is one of these per type of machine
#     Y_SITE = /env/Yorick/yorick-1.0/Yorick
#        /env is mounted to a single file server, visible from every
#        machine on the network, whatever type it is

# You must set the following variables in order to enable make to build
# your custom version of Yorick:

#     Y_HOME
#        the directory where Yorick is installed on this architecture.
#        Run yorick and type "help" to find out where Y_LAUNCH is.
#        Then try   Y_LAUNCH/../yorhome   -- if that exists and is a
#        directory containing Maketmpl, then that is Y_HOME.  Otherwise
#        you need to ask whoever built Yorick at your site.
#        exec_prefix is Y_HOME/..
#     CODE_NAME
#     NON_SHARABLE
#        the name you want to give your custom Yorick version.
#        One of these two should always be the string "unused".
#        You need to make a your first decision here:
#           If your package is intended for use in conjunction with
#           other custom Yorick packages, define CODE_NAME.  With
#           CODE_NAME, make will create a library containing your
#           object code.  This library can be loaded by yourself or
#           others in the future, who wish to include your package in
#           a their own custom version of Yorick.
#           Alternatively, if neither you nor anyone else might be
#           interested in your package at a future time, define
#           NON_SHARABLE instead.  In this case, make will not build a
#           library of your object code, but will instead load it
#           directly into this one custom Yorick.  This would be
#           appropriate if you are just adding one or two simple,
#           special purpose routines to improve Yorick performance
#           on the problem you are currently solving.
#     C_OPTIMIZE
#     F_OPTIMIZE
#        normally set to "-g" (to debug) or "-O" (to optimize), depending
#        on where you are in the code development cycle.  Normally, you
#        would use "-g" until your code is running reliably, then make
#        a final version with "-O" for actual use.  C_OPTIMIZE can be
#        any flags you want to pass to the C compiler, and F_OPTIMIZE can
#        be any flags you want to pass to the FORTRAN compiler.
#     OBJS
#        the list of object files to be built from source code in this
#        directory.  C source code should reside in files ending with
#        ".c" (or ".h" for header files); FORTRAN source file names should
#        end with ".f".  The OBJS are a space delimited list of files
#        ending with ".o" with prefixes matching the the ".c" or ".f"
#        files you want to compile.  The OBJS list can be continued onto
#        multiple lines by putting a backslash "\" at the end of the
#        incomplete lines.
#     CODE_LIBRARY
#        If you selected CODE_NAME, set this to the name of the library you
#        want your OBJS placed in.  Library names must begin with "lib"
#        and end with ".a".  If you selected NON_SHARABLE, set CODE_LIBRARY
#        to "unused.a".
#     PKG_LIBS
#     PKG_OBJS
#        If you set CODE_LIBRARY to, say, "libmy_code.a", then PKG_LIBS
#        should be set to "-lmy_code", so that your library will be
#        loaded.  If you are loading other custom Yorick libraries along
#        with your own, you must include their directories and library
#        names after your own.  Dependent libraries must be listed before
#        the libraries on which they depend.
#        In addition to libraries, you may want to load other object files;
#        if so, list them under PKG_OBJS.  You must use at least
#        "$(OBJS) $(YWRAP_O)"
#        If you are loading other people's Yorick packages (see Y_OTHERS
#        below), you need to include their libraries in PKG_LIBS (as well
#        as their include files in Y_OTHERS).  By default, this Makefile
#        will look in the following places for the libraries it needs:
#             .            (that is, Y_BUILD)
#             Y_HOME/../lib
#             Y_HOME/../contrib
#        If you are using loading a package which has not been put in
#        one of these three places, you must provide a "-Ldirectory -lpkg"
#        in PKG_LIBS.  Otherwise, "-lpkg" will be sufficient.
#        If other people might want to use your package, you will make
#        it easier for them to port their code to another platform if
#        you put your library in one of the Y_HOME directories.  If you
#        don't, you are forcing them to hunt for it on each platform.
#     Y_INCLUDE
#        In order to link your compiled routines to the Yorick interpreter,
#        you need to write a Yorick include file "my_code.i" -- put the
#        name of this file in the Y_INCLUDE variable.  (You could put more
#        than one file here.)  This file is a part of your source code, and
#        should be present in the Y_BUILD directory.  Yorick must find
#        this file (or a soft link to it) in one of the following three
#        places when it starts (it looks in this order):
#             $(Y_LAUNCH)
#             $(Y_SITE)/startup
#             $(Y_SITE)/contrib
#        If a few other people at your site might be interested in loading
#        Yorick versions which use your package, put the file into
#        $(Y_SITE)/contrib.  If most or many people need your package,
#        arrange to have my_code.i put into $(Y_SITE)/startup.
#        If other people might want to use your package, you will make
#        it easier for them to port their code to another platform if
#        you put your include file in one of the Y_SITE directories.  If
#        you don't, you are forcing them to hunt for it on each platform.
#     Y_OTHERS
#        You may want to load packages you wrote previously, or that
#        someone else has written.  If so, the name of the associated
#        "my_code.i" file(s) must go in the Y_OTHERS variable (space
#        delimited).  All these files must be found in either $(Y_LAUNCH),
#        $(Y_SITE), or $(Y_SITE)/contrib when your special Yorick starts.
#        Therefore, if the author hasn't placed them in one of the
#        Y_SITE directories, you must copy them (or make soft links
#        to them) in your Y_LAUNCH directory.  You must also have copies
#        (or links) to them in Y_BUILD, so that the codger code generator
#        can find them at compile time.  If they are in either of the
#        Y_SITE directories, you needn't worry about this detail.
#     YWRAP_O
#        Your ".i" file will normally include one "PROTOTYPE" comment for
#        each compiled function you want to call from the interpreter.
#        In this case, a wrapper function is automatically generated for
#        each of your functions.  These wrappers will be compiled into
#        an object file called "ywrap.o", which should be the value of the
#        YWRAP_O variable.  If you have written your own wrapper functions,
#        so that there are no "PROTOTYPE" comments in your ".i" file, you
#        should set YWRAP_O to nil, so that make doesn't try to generate
#        wrappers for you.
#     SYS_LIBS
#        if your code requires any additional system libraries (beyond
#        -lX11 -lm -lc), list them here.  Dependent libraries must be
#        listed before the libraries on which they depend.  Appropriate
#        -L options must be included to specify the directories in which
#        your libraries may be found.  Fortran uses additional libraries.
#        If any of your source code is Fortran, put "$(FORTRAN_LIBS)"
#        to get the basic libraries needed by the Fortran on whatever
#        platform you are compiling on.  Some platforms may have additional
#        requirements; finding these anew on each platform you port to is
#        one of the joys of Fortran programming.
#     FORTRAN_STYLE
#        New code should be written in ANSI C, which is far more portable
#        than Fortran.  The major portability problem in Fortran is that
#        the "double precision" data type is necessary on workstations,
#        but produces useless code on Crays.  If your Fortran code
#        declares all real variables "double precision", try setting
#        FORTRAN_STYLE to "$(WKS_FORTRAN)", and it may compile "as is"
#        on a Cray.  Conversely, if real variables are declared "real",
#        try a FORTRAN_STYLE of "$(CRAY_FORTRAN)".  If you can't get one
#        choice to work on all platforms, you will be stuck with maintaining
#        a separate version of your Fortran source for each platform.  Since
#        the Crays are the only deviant machine now, and since there are
#        some workstations for which there is no possible $(CRAY_FORTRAN)
#        switch, I strongly urge you to use only $(WKS_FORTRAN)
#     CLEAN_UP
#     TIDY_UP
#        Put any special filenames to be removed by the "clean" and "tidy"
#        targets here.  Don't worry about object files, library files,
#        and the like -- clean and tidy already know about them.

# After you have set all of these variables, in the next section of this
# Makefile, you need to describe the "targets" which make will build.
# The whole custom Yorick code "my_code", each object file ".o", and
# the library "libmy_code.a" containing those object files are the
# targets you are mostly interested in.

#     all::
#        The first target is always "all::".  It is special; it's what
#        happens when you just type "make".  If you selected the CODE_NAME
#        variable, use that version of "all::"; if you selected NON_SHARABLE
#        use the other version.
#     distrib::
#        A distrib target is handy for cutting a compressed tar file
#        suitable for moving this code to other sites.  See the sample.
#     my_obj.o:  my_head1.h my_head2.h
#        Each of your C source files should have a line like this one
#        stating its (local) header dependencies, if any.  You might want to
#        include special compile instructions (usually -D macro definitions)
#        here as well.  FORTRAN source usually doesn't need either
#        dependencies or special compile instructions; you don't need
#        to list any specific ".o" targets for such sources.

# ---------------------------------------------------------------------------
# Moving your Special Version of Yorick to Another Directory
# ----------------------------------------------------------

# If Y_BUILD is not where you want your special version of Yorick,
# you should move the include file(s) mentioned in Y_INCLUDE into
# either $(Y_SITE)/contrib (if only a few other people might be
# interested in using your package), or $(Y_SITE)/startup (if most or
# many custom Yorick builders will use your package).  The constraint is
# that all of the include files your version needs to start (Y_INCLUDE
# and Y_OTHERS) must be either in one of those directories, or in
# the Y_LAUNCH directory (see the discussion of Y_INCLUDE above).
# You should move your package library into either $(Y_HOME)/../lib or
# $(Y_HOME)/../contrib, corresponding to the include file(s).

# ---------------------------------------------------------------------------
# Porting your Special Version of Yorick to Another Machine
# ---------------------------------------------------------

# After saving your executable (my_code) and library (libmy_code.a),
# do a
#      make clean
# Then use the tar utility to make a copy of Y_BUILD:
#      cd ..
#      tar cvf my_code.tar My_code
# (assuming My_code is the name of your Y_BUILD directory).
# Move my_code.tar to the new platform and type:
#      tar xvf my_code.tar
#      rm my_code.tar
#      cd My_code
# Then edit Makefile, replacing the one line which sets exec_prefix with
# the pathname of the Yorick home directory on the new platform.
# Exit the editor and type:
#      make Makefile
#      make
#      make tidy
# If necessary, move your include file(s) into Y_SITE (or its contrib)
# and your libraries into Y_HOME/../lib (or its contrib), and you are done.

# ---------------------------------------------------------------------------
# Moving a Special Yorick Executable File to Another Network
# ----------------------------------------------------------

# You can move your Yorick to the same type of machine on another network
# without having to recompile it.  However, if the Y_SITE directory is
# different on the new network than on the network where you compiled
# your Yorick, you will need to install a soft link to Y_SITE in the
# Y_LAUNCH directory:
#      ln -s $(Y_SITE) $(Y_LAUNCH)/yorick.site
# (Remember, Y_LAUNCH is the directory containing your executable file.)

# ---------------------------------------------------------------------------

# If you've played your cards right, this is the only line that you
# need to change in order to port your custom version of Yorick to a
# new platform.
exec_prefix = /home/munro/1.1
Y_HOME = $(exec_prefix)/yorhome

C_OPTIMIZE = -g
F_OPTIMIZE = -g

# This sample custom Yorick is called "my_code" -- switch to your own name.
# CODE_NAME = unused
# NON_SHARABLE = my_code
CODE_NAME = my_code
NON_SHARABLE = unused

OBJS = my_code1.o my_code2.o my_code3.o

# CODE_LIBRARY = unused.a
CODE_LIBRARY = libmy_code.a

# PKG_LIBS =
# PKG_OBJS = $(OBJS) $(YWRAP_O)
PKG_LIBS = -L. -lmy_code
PKG_OBJS =

Y_INCLUDE = my_code.i
Y_OTHERS =

# YWRAP_O =
YWRAP_O = ywrap.o

# SYS_LIBS = $(FORTRAN_LIBS)
SYS_LIBS =

# FORTRAN_STYLE = $(CRAY_FORTRAN)
# FORTRAN_STYLE = $(WKS_FORTRAN)
# FORTRAN_STYLE =
FORTRAN_STYLE = $(CRAY_FORTRAN)

# Set any special files to be zapped by the clean and tidy targets.
# (make clean removes both TIDY_UP and CLEAN_UP)
CLEAN_UP = my_code
TIDY_UP=

# ---------------------------------------------------------------------------

# all:: $(NON_SHARABLE)
all:: $(CODE_LIBRARY) $(CODE_NAME)

distrib::
	$(RM) *.tar*
	$(RM) -r My_code
	mkdir My_code
	cp README Makefile *.h *.y *.c *.f my_code.i My_code
	tar -cvf my_code.tar My_code
	gzip my_code.tar
	$(RM) -r My_code

# Note: indirectly included headers separated by three spaces

my_code1.o: my_code1.h   my_code.h
my_code2.o: my_code2.c my_code.h
	$(CC) $(CFLAGS) -DSPECIAL_SWITCH -c my_code2.c
my_code1.o: my_code3.h   my_code1.h my_code.h

# ---------------------------------------------------------------------------

# Do not modify or remove the following line.
# --END-CODE-SPECIFIC-SECTION-----------------END-CODE-SPECIFIC-SECTION--
