OS/2 Shareware BBS: 22 gnu/22-gnu.zip/bakev100.zip/bake.doc

Text File | 1995-05-22 | 16KB | 360 lines

Bake V1.0 docs, by Rob Landley.

1) What is bake
2) How to use bake
3) The bake file "target" line
4) Bake file "source" lines.
5) Command line arguments to bake
6) Extra compiler arguments
5) bakefile.1 and bakefile.2

******************************* What is Bake? *****************************

Bake is a project manager utility for quickly and easily compiling large,
multi-file C/C++ programs with the EMX port of GCC under OS/2. The old way
to do this was to use "Make" files, which were incredibly complex and a lot
of work to maintain.

With bake, you make a very simple data file to tell it what to do, and
it does all the work for you.  You don't have to learn the command line
arguments to gcc, emxomfar, ar, rc, or any of the files bake shells to.
You also don't have to list the dependencies in your C++ and Resource
files, bake will look through the files and figure them out, recursively
checking the headers for more included files when necessary.

The name "bake" is derived from "better make".  It also describes a
process of combining ingredients and performing a strange ritual on them
whereby you come up with a finished product, which seemed appropriate.

When learning how to use bake, the following rule of thumb may come in
handy:  "If I don't understand something becuase I haven't learned about
that yet (like .dll files or unix emulation), I'm probably not going to
be using it yet, so don't worry about it."

This file won't teach you how to write OS/2 programs, just how to compile
them easily via the EMX package.  I may write a text file on "How to
program for OS/2 with the EMX package" if I get time, but I haven't yet.

*************************** How do I use bake? ****************************

For each project, you will need to create a text file to tell bake what to
do.  The default name for this file is "bakefile", and there are only two
types of lines in a bake file.  The first non-blank line is the "target"
line, which tells bake what file it's creating.  The rest are "source" lines
which tell it what files the to make the target out of.  Each file will be
recognized by its extension, and processed accordingly.  Everything
after a semicolon is ignored as a comment.

The following is a sample "bakefile":

   filename.exe      ; The target line  (32 bit native OS/2 executable)
   file1.cc          ; The first source file
   file2.cc          ; The second source file
   file3.cc          ; The third source file

The following is a more complex sample "bakefile":

   compress.dll      ; This time the target is a ".dll" file.
   compress.def      ; The module definition file (mandatory for ".dll"s)
   toolkit.def       ; Another ".def" file (perhaps using another .dll)
   compress.rc       ; The resource file (it's accessing the PM.)
   main.cc           ; Some actual source code.
   archive.cc        ; More C++ source code.
   ..\huffman.obj    ; A pre-compiled .obj file.
   dirtree.cxx       ; This is also a C++ file.
   bsd.lib           ; Link with this library.

To use a bake file, type "bake" and press enter.  "bake.exe" must either be
in your path somewhere, or in the current directory.

********************** The bake file "target" line. **********************

The very first line of a bake file is the "target" line, which tells bake
the name of the file it's trying to create.  The file name of the target
file must end in one of the following extensions:

  OS/2 extensions:

  ".exe" : Bake a 32 bit native OS/2 executable.
  ".lib" : Bake a 32 bit native OS/2 static library.
  ".dll" : Bake a 32 bit native OS/2 dynamic link library.

  Unix emulation (via EMX) extensions:

  ".emx" : Bake a full Unix emulation executable.
  ".a"   : Bake a unix static library file.
  ".em2" : Bake a hybrid Unix & OS/2 executable.


The ".emx" and ".em2" extension will actually create files with the
extension ".exe", but they will require access to the EMX unix emulator
to run.

Full Unix emulation executables are actually Unix executables, which call
the Unix emulator "EMX.EXE" to run under DOS and "emx.dll" to run under
OS/2.  These executables are compiled via Unix style ".o" object files
and Unix style ".a" static library files.  Only this executable format
uses those two types of files.  Full unix emulation produces big, slow
executables, but they are extremely unix compatible (even producing core
dump files after a crash), and can run under dos as well as OS/2.

Hybrid executables (which also end in the extension ".exe") contain some
Unix code and some OS/2 code.  Because of this, they are smaller and
faster than fully emulated executables, but can only be run under OS/2.
Hybrid executables are still highly compatible with Unix, and require the
Unix emulator "emx.dll" to run.  Hybrid executables use OS/2 style ".lib"
and ".obj" files.

The target file can have a path, if necessary.  Bake doesn't care as
long as it recognizes the extension and can open or create the file.

************************ Bake file "Source" lines ************************

The rest of the lines in a bake file name one source file each.  These
files will be compiled and linked as efficiently as possible to create the
target file named on the first line.

Source files must have one of the following extensions:

  Source code files:

  ".cc"  : C++ source code
  ".cxx" : C++ source code
  ".cpp" : C++ source code
  ".C"   : C++ source code    (capital C)
  ".c"   : ANSI C source code (lower case C)

  Optional files:

  ".def" : Module definition file.
  ".rc"  : Resource file.
  ".res" : Pre-compiled binary resource file.
  ".obj" : Pre-compiled OS/2 object module.
  ".lib" : OS/2 static library.

  Full unix emulation only:

  ".o"   : Pre-compiled Unix style object file.
  ".a"   : Unix style static library.

Each source code file will be compiled to create an object module file. If
the corresponding object file already exists, the date of the file will be
compared with the date of the source file, and (recursively) the header
files included from the source file.  Only header files included with quotes
(#include "file.h";) will be tested.  The library header files included with
"#include <file.h>;" will not be tested.  If the object file is newer than
all of the files it was created from, it will not need to be re-compiled.

If a source code file listed has a path, such as "..\common\file.cxx",
the object module created/tested against will be in the same directory as
the source file.  All files without a path will be expected to be in the
same directory as the Bake file (except ".lib" files, which have their
own search path defined in the environment variable "LIBRARY_PATH").

--- Module definition files in "source" lines:

Module definition files are required for creating Dynamically Linked
Libraries (.DLL files), load-time linking with .DLL files, and creating
Presentation Manager programs.  For text mode apps, module definition files
are optional, although they do allow you to declare a larger stack than the
default.  (A stack size of at least 32768 bytes is needed for any PM
program.)  Module definition files are only used during the linking phase.

--- Resource files in "source" lines:

Resource files ("*.rc") will be compiled to binary format ("*.res") if
the currently existing .res file is older than the .rc file itself, or
older than any file #included (or rcincluded, or an icon file) from the
.rc file.

You cannot list two resource files in the same bake file.  You must use
the rcinclude statement in the resource file instead.

--- Object modules in "source" lines:

If a "source" line of a bake file actually names an object file (with the
extension ".obj" or ".o"), the module cannot be recompiled, but will be
linked into the target file.  It is best to only directly list object
modules you do not have the source code to.  Otherwise just name the
source code file, and if it doesn't need to be recompiled, it won't be.

--- Library files in "source" files:

Your program will be linked with any optional libraries given in the bake
file (with the extension ".lib" or ".a").  These libraries will be checked
in the order they appear in the bake file.  You do not have to mention
the default libraries in the bake file, they are assumed.

If the target is a library, and you have another library as a source file,
the entire second library will be included in the target.

Dynamic Link Libraries (".dll" files) do not need to be listed in the
bake file.  If you want to link them at load time you must include
a module definition file (".def") or static import library (".lib") for
each one.  Run time .dll linking is handled manually by the C/C++ source
code, not by bake.

An interesting library supplied with the EMX package is "wrap.lib", which
is the static import library for the ".dll" version of the OS/2 API call
library.  If you link with this library, your program will use the .dll
version of the OS/2 API call library, reducing the .exe size at the expense
of requiring an extra file at run time.  This is not recommended for ".emx"
type executables.

--- Linking:

Once all the files that need to be recompiled have been, Bake will link
them to form the target file.  If an existing target file is newer than
all the component files it was created from, it will not need to be
re-linked.

************** Command line arguments to Bake (optional): ****************

You can probably safely ignore all of these.

Bake takes two command line arguments, both of which are optional:

-- The first argument

The first argument to bake is the the name of the bake file.  If you
have a bake file called "herbert", type "bake herbert" and it'll use
that file instead to compile your program.  If you run bake.exe with no
arguments, it will look for a file (in the current directory) named
"bakefile".

The default directory bake uses during compilation is the directory the
bake file is in.  If you give it path to the bake file on the command line,
bake will change to that directory, do its stuff, and then change back to
the origional directory before exiting.  In other words, relative paths
for source and target files, such as "..\file.cc", will be interpreted as
starting from the directory the bake file resides in, not from the directory
bake itself was run in.

-- The second argument:

The second argument to bake is a group of letters which select various
optional features.  These letters are Q,V, and A.

Q)  Quiet mode.
    Don't output anything that isn't an error message.

V)  Verbose mode.
    Display lots of useless details about what bake is doing.

A)  Recompile all files.
    Rebuild entire from scratch, ignoring all existing intermediate files.
    This usually takes a lot longer than a normal run of bake, but may
    be necessary if extra compiler arguments have been added to the bake
    file.

C)  Clean up intermediate files.
    Delete all .obj files and .res files created by bake.  Use this only
    if you don't intend to recompile the project again any time soon, or
    if you're really short of hard drive space.  If "C" appears more than
    once in the options, (I.E. "bake filename cc",) no new compiling will
    be done.  Otherwise bake will attempt to re-create the current project,
    if it needs it, before deleting the temp files.


Example:  bake ..\project1 acv

That would use "project1" as the bake file, to be found in the directory
above the one bake was run in.  It also tells bake to re-compile all files
from scratch, to delete all the intermediate files after it finishes,
and to display verbose output.

****************** Extra compiler arguments (optional) *******************

Bake automatically supplies most of the command line arguments GCC needs.
You can also supply additional arguments to the compiler by putting them
into the bake file.  Extra compiler arguments go after the file name on
a given bake file line.

Arguments that go on the target line (the one that names the file to create)
will take effect globally.  They will be supplied to the compiler for every
source file in the project, and will also be supplied to the linker.  A
few that might come in handy are:

  "-Zmt"     : Multi-threaded code (can use C runtime library functions)
  "-Zcrtdll" : Use the ".dll" version of the C runtime library (".emx" and
               ".em2" type executables only, not currently implemented for
               OS/2 native executables.  That's an EMX package limitation.)
  "-Zso"     : Make a ".dll" file "Stand Alone", with its own run-time
               environment.

Arguments that go after a source file will be supplied only when that one
file is being compiled.

Example:

  myfile.exe -Zcrtdll -Zmt
  file1.cc
  file2.cc -mprobe
  file3.cc
  file4.cc

GCC is to compile all four of the .cc files as multi-threaded code, and
use the multi-threaded ".dll" version of the C runtime library.

Only file2.cc will generate "stack probes", which are extremely technical
and have to do with allocating stack space properly under unusual conditions.
Don't worry about it, it's just an example.

--- Default command lines arguments:

The following are approximately the default command line arguments for the
various compilation modes (where * is a list of files of the type given).

You can safely ignore all of this:

".exe"
Compile: gcc -pipe -O2 -Zomf -c *.cc
Link   : gcc -pipe -s -o target.exe -Zsys -Zomf *.obj *.res *.def -l*.lib

".dll"
Compile: gcc -pipe -O2 -Zomf -c *.cc
Link   : gcc -pipe -s -o target.dll -Zdll -Zsys -Zomf *.obj *.res *.def -l*.lib

".lib"
Compile: gcc -pipe -O2 -Zomf -c *.cc
Link   : del target.lib;emxomfar r target.lib *.obj

".emx"
Compile: gcc -pipe -O2 -c *.cc
Link   : gcc -pipe -s -o target.exe *.obj *.res *.def -l*.lib

".a"
Compile: gcc -pipe -O2 -I. -DOS2 -c *.cc
Link   : del target.lib;ar rs target.lib

".em2"
Compile: gcc -pipe -O2 -Zomf -c *.cc
Link   : gcc -pipe -s -o target.exe -Zomf *.obj *.res *.def -l*.lib

**************************** bakefile.sam *******************************

Bake is compiled in "em2" mode (OS/2 optimized unix emulation) with the
-Zcrtdll option (it uses the .dll version of the C runtime library), and
linked with "wrap.lib" (the export library for the .dll version of the
OS/2 API calls.)  This produces the smallest possible executables, but
requires access to several .dll files (emx.dll, emxlibcs.dll, and
emxwrap.dll).  All of these files are available in the EMX runtime package.

The actual bakefile used to compile bake.exe is provided as a sample
(bakefile.1) as well as a variant used to compile an OS/2 native version
that requires no .dll files (not distributed, just tested).  Look at them,
make your own, and try it out.  There's really not much more to explain.

************************* Contacting the Author **************************

My name is Rob Landley, and if you leave a message to me on the fidonet OS2
echo, I'll probably get it.  My fidonet and internet email addresses are
about to change, because I'm moving.  The old internet address was
"[e-mail]", but who knows how long they'll hold that now
that I've graduated.  The next version of bake (of COURSE there will be
bugs!) should have new email addresses I can be contacted at.

Have fun programming for OS/2 with EMX.

Rob