Hall of Fame/HallofFameCDROM.cdr/misc2/smaint2b.lzh/NEW2MAKE.TXT

Text File | 1991-05-27 | 11.0 KB | 275 lines

****************************************************************************
****************************************************************************
                              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.