****************************************************************************
****************************************************************************
                              NEW2MAKE.TXT
          For Programmers Who Are New To Using Make Programs
****************************************************************************
****************************************************************************


If you are new to make programs reading this file before reading the manual 
or using SUPER-MAINT should be helpful.  Program maintenance can seem 
complicated, but once you begin using a make utility it can be a real time 
saver.

****************************************************************************
WHAT IS A MAKE UTILITY?

Make utilities are normally used to build programs out of multiple source 
code files.  Let's use the SUPER-MAINT  sample program as an example.  It 
is written in three source code files:  SAMPLE.C, SAMPLE1.C, and SAMPLE2.C.
To compile and link these from the command line we need to do it in four 
steps:

                         compile SAMPLE.C
                         compile SAMPLE1.C
                         compile SAMPLE2.C
                         link the 3 modules together

A make utility turns this into a one step process.  All of the instructions 
for building your program are written into a text file called a `make file.'
When you call the maker with the make file it goes down the list of 
instructions, performing each as it goes along.

The above paragraph could just as easily describe batch files.  What 
distinguishes make utilities is that each instruction is only carried out if 
an IF:THEN condition is met.  This condition always has to do with the age of 
the files you use to build your program.  Consider the first command:

                         compile SAMPLE.C

In a make file this would look like this:

                         SAMPLE.OBJ: SAMPLE.C
                                 compile SAMPLE.C

The command is saying, "If SAMPLE.C is newer than SAMPLE.OBJ, then compile 
SAMPLE.C.  If the age of the files is the same do nothing."  If you are 
working on a big project this saves time, because the maker automatically 
knows only to compile the parts of your program that have changed since the 
last time you built it.  (Compiling and linking the SUPER-MAINT Editor took 
about 15 minutes on a 386 machine.  Most builds using SUPER-MAINT only took 
a minute or two, because ONLY THE NEW MODULES HAD TO BE COMPILED.)

The link command would look like this:

                         SAMPLE.EXE: SAMPLE.OBJ SAMPLE1.OBJ SAMPLE2.OBJ
                                 link SAMPLE.EXE

It is saying, "If SAMPLE.OBJ, SAMPLE1.OBJ, or SAMPLE2.OBJ is newer than 
SAMPLE.EXE, then link the program."  As you can see there can be multiple 
dependencies.  In make file jargon a "target" is the file you are building 
(SAMPLE.EXE), and a "dependent" is the file or files that must be newer 
than the target if the target is to be built (the .OBJ files listed after 
the colon).

Here is what the whole make file would look like:

                         SAMPLE.OBJ: SAMPLE.C
                                 compile SAMPLE.C

                         SAMPLE1.OBJ: SAMPLE1.C
                                 compile SAMPLE1.C

                         SAMPLE2.OBJ: SAMPLE2.C
                                 compile SAMPLE2.C

                         SAMPLE.EXE: SAMPLE.OBJ SAMPLE1.OBJ SAMPLE2.OBJ
                                 link SAMPLE.EXE




****************************************************************************
HOW ARE MACROS USED?

Like many programs, make utilities can use macros (a set of commands that 
have been assigned to one short command).  Let's say you want to include 
debugging information in your program.  Your compiler has special flags 
that you call it with to include this information for the debugger.  You 
could build a macro with these flags, and another that you would use for 
building your program after it has been debugged.

DEBUG = flags to build with debugging info
NODEBUG = flags to use for the final program build.

Now to include the debugging flags you could use this command in your make 
file:

                         SAMPLE.OBJ: SAMPLE.C
                                 compile $(DEBUG) SAMPLE.C

To use the flags for a finished program you would use:

                         SAMPLE.OBJ: SAMPLE.C
                                 compile $(NODEBUG) SAMPLE.C

****************************************************************************
WHY IS SUPER-MAINT EASIER?

Programmer's SUPER-MAINT is easier than most other makers because:

1.  It builds your make file for you, and other useful files like response 
    files for your linker.

2.  It makes use of macros.  Specific macros can be called with simple 
    command line flags so you don't have to remember macro names or 
    complicated commands.

3.  Once you have called the maker from the command line it remembers which 
    flags you called it with and which make file you called.  You don't have 
    to re-enter this information unless you are changing some of it.  Thus, 
    if you are building three programs with all the same parameters you would 
    type:

                               sm -3 -d prog 1
                               sm prog2
                               sm prog3

    (You don't have to re-enter the `-3 -d' flags).

****************************************************************************
WHAT IS A RESPONSE FILE?

Some programs ask you questions about what you want them to do as they go 
along.  Some examples are linkers, librarians and assemblers.  Each time one 
of these programs needs more information from you it stops to ask for it.

A response file automates the process.  You provide the answers to the 
questions in advance, and tell the program to look for the answers in the 
response file.  This way it can do its job without stopping to bother you.

A linker needs to know such things as what files to link, what to call the 
executable file (the finished program), what to call the map file, the names 
of the libraries you want to link into your program, and so on.  An example 
might look like this:

                         sample.obj+
                         sample1.obj+
                         sample2.obj
                         sample.exe
                         sample.map
                         mylib1+
                         mylib2

Notice the plus signs.  These tell the linker there are more object files 
or libraries to link.  Different linkers (and other programs) use various 
methods and symbols (& instead of +, for example), depending on what 
questions the program asks and the order it asks them in.  See your compiler 
manual for the appropriate response file format for your language.

****************************************************************************
SOME NOTES ABOUT HOW SUPER-MAINT DOES WHAT IT DOES

If you want to build your own make files you may do so.  You can use 
SUPER-MAINT macro sets (if so you must use a whole set), or not, as you 
choose.  You may also define your own macros for use with the macro sets, 
or by themselves.

**********
THE MACROS

SUPER-MAINT makes the business of building a program easier by keeping 
commands in sets of macros.  Depending on the flags you use at the command 
line, only certain macros are called by SM.EXE (the maker).  SUPER-MAINT 
macros, when put together, comprise the command line for your compiler (or 
linker, etc.).

Let's use the following macro set for an example:

L1C0 = -c
L1M1 = /AS
L1M2 = /AM
L1M3 = /AL
L1ND =
L1D = /Zi /Od
L1F1 = /W4
L1F2 = /Os /Zr

For each language you use (C, Assembler, etc) SUPER-MAINT needs a full set 
of macros.  Notice that one of the macros in the example is empty.  It must 
be part of the set, even if you don't assign any value to it.

Not all the macros are used each time you call SM.EXE.  However, the macros 
that ARE used are always called in the same order, from top to bottom.

These macros are ALWAYS called:

xxCO      the flag for the compiler to compile without calling the linker
xxF1      any miscellaneous flags you want
xxF2      same as xxF1 (when set for Borland languages this is called AFTER
          the name of the file to compile

Only one of these macros is called:

xxM1      the flag for the first memory model
xxM2      the flag for the second memory model
xxM3      the flag for the third memory model

You define up to three memory models.  The compiler flags for those models 
are stored in the above macros.

Only one of these macros is called:

xxND      the flags used for a final program build
xxD       the flags needed to include debugging information in your program

SO!  If you called SUPER-MAINT at the command line:

                 sm -1 -n sample

it would call your compiler like so:

              cl /c /AS /W4 /Os /Zr sample.c

OR if your called SUPER-MAINT:

                 sm -3 -d sample
it would compile:

              cl /c /AL /Zi /Od /W4 /Os /Zr sample.c

Notice that for each example, the macros that are used are called in the same 
order.

******************************
USING SME.EXE TO AUTOMATE THIS

SME has two areas to keep your macro set information: a permanent area 
(language definition files), and a temporary area (LASTMACS.SM).

Language Definition Files:

There are five language definition files.  Three are for programming 
languages, one is for the linker and one for the librarian.  if you don't 
use all of these you may have blank "lang def" files.  You keep permanent 
information, including compiler flags you ALWAYS use, in the lang def files.  
You can edit these files using the "Toolbox" "Lang Def Files" choices in 
SME.EXE.

LASTMACS.SM:

Information that is used for your current project is kept in a file called 
LASTMACS.SM.  You get to this file using the "Make" "Macros" choices in 
SME.EXE.  Usually you will start with the permanent settings in your lang def 
files.  You use alt-r to get these settings.  Then you can press alt-e to edit 
each macro, adding special flags as needed.  For example, if you are editing 
the linker macros you may want to add a stack size command.

****************************
RESPONSE FILES AND LIBRARIES

If you are building your make files with SME.EXE SUPER-MAINT requires that 
your linker (or librarian) use a response file.  

SME.EXE will build the response file automatically from the information you 
set up in SMSET.EXE (the setup facility.  This can be accessed from the 
"Setup" menu in SME.EXE).  It is particularly important to set up your 
library names prior to building a response file.  

The libraries are called in the order you list them.  So if your language 
requires libraries to be linked in a certain order you should list them in 
that order.

Also, some brands require you to list the full path of the library.  Refer to 
your compiler manual to see if you have to do this.
