OS/2 Shareware BBS: 10 Tools/10-Tools.zip/cshell69.zip/ENGLISH.DOC

Text File | 1992-05-21 | 27KB | 641 lines

CS 6.8 - Compiler Shell - (c) Kai Uwe Rommel - Jan 18 1992


1. Introduction
---------------

CS is a driver program or shell for the following
Microsoft program development tools:

- Macro Assembler (5.00 and newer, 6.00 is supported)
- C Compiler (5.00 and newer, 6.00 is supported)
- 386 C Compiler
- Pascal Compiler (4.00 and newer)
- FORTRAN Compiler (4.00 and newer)
- Windows Resource Compiler (2.00 and newer)
- Whitewater Ressource Toolkit for Windows
- OS/2 Resource Compiler
- LINK (5.00 and newer), LINK386
- ILINK
- BIND
- EXE2BIN
- CVPACK
- LIB (3.08 and newer)
- PWBRMAKE

In addition, the following programs are supported:

- FLEX scanner generator (2.3 and newer)
- GNU BISON parser generator (1.03 and newer)

CS simplifies the usage of these programs and preserves you from
typing of often used options and commands, looks for files in configured
directories and calls your compiler(s) with a MAKE-like strategy.

You do not have to create a complicated description of all dependencies
and commands in a makefile. Instead, you write the names of all input
files of a project into a CS project file (see below) together with
some options or enter them directly on the command line (depending of
the size of your project). CS detects the file types from the extension
of their names and automatically knows, what it has to do with them,
call a compiler, add them to the LINK or BIND command and so on.
It also knows from the file dates which files are out of date and have
to be recompiled and which files are up to date. This is similar to the
strategy of the MAKE program. Another feature of CS is, that it allows
you to maintain sets of often used options for the compilers and the
linker in sections of the CS.INI file. All configuration data for CS
is also held in CS.INI.

CS is a family mode application and runs under MS-DOS and under OS/2
in both real and protected mode.

The following program file types can be produced from your sources using CS:

   - DOS (EXE format)
   - DOS (COM format)
   - Windows or WLO (Windows Libraries for OS/2)
   - Mirrors (Windows Emulation for OS/2)
   - OS/2 (16- and 32-bit)
   - OS/2 Presentation Manager (16- and 32-bit)
   - Family applications for OS/2 and DOS or DOS Box of OS/2

   For Windows/WLO, Mirrors, OS/2 and OS/2 PM also DLL's can be generated.

Other output files:

   - linker maps
   - listings
   - object libraries


2. Syntax
---------

Usage:    CS argument*

    argument  = globalopt | fileset
    fileset   = filespec  | '(' item+ ')'
    item      = localopt  | filespec | '(' special ')'
    special   = genopt    | filespec
    filespec  = filename  | filename '{' filename+ '}'

Where:    globalopt ε { -? -H -Am -Ff -Le -Sn -Oid -Q -I -F -X -P
              -C -L -E -N -B -M -LS -SB -K -NS -NF }

        m         = model identifier T, S, M, C, L, H or MT
        f         = float type identifier E, 7, A or D
        e         = program type identifier R, C, P, PM, B, W or L
        id        = name of CS.INI section with compiler options
        n         = stack size in bytes (decimal or hex with prefix 0x)

    filename  = any valid DOS filename, all filenames in a fileset in ()
            must have the same extension (C, PAS, FOR or ASM)
    localopt  = any option available for the compiler associated with the
            extension of the files in a fileset
    genopt    = any parser or scanner generator option

Input files can have the extensions C, PAS, FOR, ASM, L, Y, OBJ, LIB, RC, RES
or DEF (linker definition file), BAD (list for BIND of symbols to be
bound to BadDynLink) or CS (CS project file). The '(' special ')' argument
is only allowed for files with L or Y extensions. A file with extension MDT
can also be given, to specify the file for incremental compilation info of
the C 6.00 QCC (see option -Q). Files with extensions LOG or BAT/CMD
specify the names of files for the screen log or batch file to generate.
BSC specifies the PWB browser database file to create or maintain.

When a directory name is passed as an argument, it is used as the output
directory. It must be specified as the first non-option argument.

To specify additional API libraries/objects for BIND instead for LINK (they
have the same extension), append an exclamation mark directly to the name of
the library/object to distinguish it from LINK libraries/objects. CS looks
for BIND API libraries through the PLIB variable and for additional BIND
API objects through the OBJ variable (see section 5.1).

If there are special options for one ore more source files to the compiler
associated with their type, they can be enclosed with the files for
which they should be used in parentheses. For all filesets enclosed
in () the compiler is called separately (normally, the compilers are
called with as much file names as arguments as fit on the command line,
for those compilers that support multiple file arguments, namely CL and FL).
For FLEX and BISON source files, both options for these programs and for
the C compiler can be given (see below).

To help CS to handle more complicated dependencies, one or more files
can be associated with each source file, which depends on them. This is
often useful for include or header files. All names of files on which
a particular source file depends, must be enclosed in curly brackets {}
and follow the source file immediately. This files are used ONLY for
the MAKE-strategy, i.e. to determine if a source file has to be recompiled
or not.

If there are files given on the command line or in the project file
with extensions EXE, SYS, DLL, COM, MAP, LST or BSC, then these names define
the names of the output files and define their type (EXE/COM/DLL) or cause
their production (MAP/LST/BSC) if given. That means, if you give the names
FOO.COM and BAR.MAP as arguments to CS, it will try to compile the source
files to a DOS COM program named FOO.COM and it will tell LINK to write
a link map to the file BAR.MAP. DLL and SYS are just synonyms for EXE. To
create a DOS SYS device driver in binary format, the option -LC has to be
specified in addition to the SYS name, but DOS can also load device drivers
in EXE format.

Example:
CS -lp main.c{def.h} prog.exe (mod1.c mod2.c -Gt) mod3.asm mod4.c mod5.pas

(If this appears to be cryptical of difficult to type, this shows the
usefulness of CS project files, see the equivalent project file below.)

Wildcard expansion is supported, with the restriction, that names containing
wildcards have to be separated with blanks from the context on both sides.
Wildcard expansion is not supported in project files.

Wrong:  CS main.c (mod*.c -G2)
Right:  CS main.c ( mod*.c -G2)

For BISON and FLEX, it is often needed to specify options for these
generators as well as for the C compiler, when it is called to compile
the generated C programs. For this purpose, a second () nesting level
is allowed for BISON and FLEX source files (but only for these).

Example: CS -lp main.c (-W1 (-d grammar.y))

The -d option is passed to BISON while the -W1 option is passed to the C
compiler when called to compile the generated grammar.c.
This is not a true nesting level but only a way to separate the options.
Therefore, in the following example

CS -lp main.c (-W1 (-d gram1.y) (-v gram2.y))

the -d AND the -v options are passed to BISON for BOTH grammar files.
The correct syntax for this purpose is

CS -lp main.c (-W1 (-d gram1.y)) (-W1 (-v gram2.y))

The BISON and FLEX generators are called with the appropriate options to
create output files with the same base name as the input file, but with .C
extension. The output files are created in the same directory where the input
files are, NOT in the OUTPUT directory (see section 5.1).
Therefore, the -t option of FLEX and the -o option of BISON must not be used.
They are always used by CS.


3. CS project files
-------------------

If CS encounters any file with extension CS in its arguments, the
contents of the file is read and evaluated if it was given as arguments.
The text read from the file is logically placed on the command line
instead of the file name. These files are called PROJECT FILES.
They can have any number of lines but must not contain wildcards
in filenames listed in them.

The extension CS of project files can be omitted. This is the ONLY
type of file known to CS of which the extension is optional. That means
you only have to enter "CS foo" if FOO.CS exists in the current directory
or in any directory listed in the SOURCE variable (see below).

For better readability, the text of a project file can (should) be
written on multiple lines. Lines starting with ; or # are treated as
comment lines and are ignored up to the next line feed.

CS project files are intended for bigger projects which consist of
many files and more complicated dependency trees or special options.
The usage of () and {} on the command line is not very comfortable,
for projects which require their usage, you will probably use
project files.

Such a project file is MUCH shorter and easier to wite than a makefile.
For programs like GNU awk or perl (widely used freeware programs) the
makefiles are 100 or more lines long but the equivalent CS project files
fit into 10 lines. Also, they require less "debugging".

The project file for the sample command line above could look like:

; Project: xyz
; Date:   1.4.1989
;
; main module
main.c {def.h}
;
; subroutines with special options
(mod1.c mod2.c -Gt)
;
; other subroutines
mod3.asm
mod4.c
mod5.pas
;
; output file name for family mode application
prog.exe -lb

If CS is called without any arguments or the arguments to CS do not
contain any file name of a source file with extension C, PAS, FOR, ASM or
OBJ, it looks fo a file PROJECT.CS in the current directory. If it
exists it is read as if it was given to CS as an argument. This makes
the functionality of PROJECT.CS almost like "makefile" for the standard
make utility.


4. Options
----------

-Am     Defines the memory model for C, FORTRAN and MASM. To MASM, the
        model is passed as "-Dmodel=small" etc. which requires your
        sources to contain a statement like "% .MODEL model" at the very
        beginning of the text if you want to choose the memory model at
        compile time for assembler programs.
        For m the letters T, S, M, C, L, H and MT are valid. MT stands for
        the custom model for multithreaded OS/2 programs with LLIBCMT.LIB.
        T (tiny) is only valid for C 6.00 and newer. 3 selects the 386 small
        model and 386 compiler and linker.

-Le     Defines the output format of the linker (e = R, C, W, P, PM, B oder L).
-LR     -> Real-Mode-EXE for DOS
-LC     -> Real-Mode-COM for DOS
-LW     -> Windows-EXE for DOS-Windows or OS/2-WLO
-LM     -> Mirrors-EXE for OS/2
-LP     -> Protected-Mode-EXE for OS/2 (without Presentation Manager)
-LPM    -> Protected-Mode-EXE for OS/2 (with Presentation Manager)
-LB     -> Bound-EXE
-LL     -> LIB is used instead of LINK to create an object library
           where the object modules of all sources are put.

-Ff     Defines the type of the floating point arithmetics.
-FE     Floating point with emulator.                    This also influences
-F7     Floating point with 80x87 coprocessor.           the type of standard
-FCE    Floating point with calls to emulator.           library used !
-FC7    Floating point with calls to 80x87 coprocessor.
-FA     Alternate floating point library.
-FD     Decimal arithmetics (only for Pascal).

-Oid    The id selects the section in CS.INI with the compiler options
        to be used. CS looks for a section named [CS-id]. From this section
        the values for the environment variables CL, PL, FL, MASM and LINK
        are read. The id should be 15 characters or less in length.

-Sn     Defines the stack size for the linker. It can be entered decimal
        or hex with the prefix 0x (standard C notation).

-C      Compile only.

-L      Link only.

-E      Echo all commands before executing them.

-N      No execution of commands, only show them.

-G      No execution of commands, but generate batch file.

-K      Keep logfile of all program output (see below).

-B      Don't use MAKE strategy, build all files regardless of file dates.

-X      Link without standard libraries.

-Q      Compile incrementally with QCC (only C 6.00 and newer)

-I      Link incrementally with ILINK whenever possible (see below).

-F      Compile and link normally (full).

-P      Call CVPACK if the output executable contains debugging information.

-M      Create a linker map and, if -LB is used, also a binder map.

-LS     Create compiler listings.

-SB     Create PWB source browser database (with BSC extension).
        This is currently only supported by C 6.00 and MASM 6.00 but no
        other languages. The SBR files from each C module are created in
        the output directory automatically but you can optionally specify
        the name and path of the BSC file.

-NF     Use full qualified path names when passing names of source files
        to the compilers. This is useful when using CodeView because it
        can always find the source files even if they are not in the
        current directory.

-NS     Opposite of above option. Use simple file names whenever posible
        except for the source files located via SOURCE variable.


5. CS.INI
------------

The characteristics of your system needed for CS have to be configured
in the file CS.INI. This file must be accessible through environment
variables INIT or PATH. It is similar in its format to WIN.INI of Microsoft
Windows. Each program that knows about it can create sections denoted
with "[name]" and store data in it in "name=value" or "name:value" formats.
That makes it ideal as a system-wide database for initialization and
configuration information. The OS2.INI file is an extension of this
method but uses a binary format not readable by humans.
See the sample configuration in the enclosed CS.INI. You can copy this file
to your own CS.INI and modifiy the setting for your needs.


5.1. Section [CS]
-----------------

In this section various default values for CS are specified that can
be overridden by command line options or project files.

MODEL=<model>
Valid models are TINY, SMALL, MEDIUM, COMPACT, LARGE, HUGE or MTHREAD.
This defines the default memory model if no -Am option is used on the
CS command line or in a project file. Equivalent to -Am option.

EXETYPE=<type>
Valid types are DEFAULT, DOS, COM, OS2, OS2PM, BOUND, WINDOWS, MIRRORS
or LIBRARY. If DEFAULT is specified, depending on the machine mode
either DOS or OS2 is choosen automatically. When LIBRARY is used,
all object modules are written to an object library with LIB and
no EXE file is created. Equivalent to -Le option.

FLOAT=<type>
Valid types are EMULATOR, 80X87, CALLEMULATOR, CALL80X87, ALTERNATE or DECIMAL.
Equivalent to -Ff option.

OPTIONS=<id>
Specifies the name of the CS.INI section with the default compiler
and linker options. Equivalent to -Oid option.

NAMES=FULL or NAMES=SHORT
Equivalent to -NF and -NS command line options (see above). This
specifies default behaviour, if none of the both command line options
is used.

BUILD=NO or BUILD=YES
The setting BUILD=YES disables the MAKE strategy of CS. Normally,
BUILD=NO should be used. See -B command line option.

MASM=5 or MASM=6
This setting tells CS if MASM version 5.00 or 5.10 is used or the new
ML.EXE driver of MASM 6.00 is used.

STACK=<size>
Defines the default stack size for LINK. Equivalent to -Sn option.

ILINK=<options>
Defines the options to be used for link in order to prepare an executable
file for incremental linking (seem ILINK manual). It should contain
/PADC:x and /PADD:y options but not the /INC option. Set x and y after
your personal requirements. No command line equivalent.

RAMDISK=<path>
If a nonempty path is specified that points into a RAM disk, then some
header or include files for the compilers to be called later are copied
to this directory if they are not already there. This can reduce harddisk
access considerably. List the path in your INCLUDE variable too (see below).
See section 4.3.

SOURCE=<pathlist>
You can define several directories in PATH syntax which are searched
for source files that were specified on the command line or in a project
file but do not exist in the current directory. CS searches using this
variable for file of types ASM, C, PAS, FOR, DEF, BAD and CS.

OBJ=<pathlist>
Same purpose as SOURCE but used to search for object files.

OBJ386=<pathlist>
Same purpose as SOURCE but used to search for 386 object files.

OUTPUT=<path>
Specifies the output directory for all files created by the programs
called by CS. Best is to let it point to a big RAM disk. If you want to
override this setting on the command line or in a project file,
include drives or paths to the file names.

INCLUDE=<pathlist>
INCLUDE386=<pathlist>
TMP=<path>
These variables specify the values of the environment variables with
the same names that are set before the compilers and the linker are called.
INCLUDE386 is used for INCLUDE when the 386 C compiler is called.

RLIB=<pathlist>
PLIB=<pathlist>
PLIB386=<pathlist>
WLIB=<pathlist>
These variables define the value of the LIB environment variable for
the linker. RLIB is used when real mode programs (EXE or COM) are created,
PLIB is used when protected mode programs (with or without PM and bound
programs) are created (PLIB386 for 32-bit protected mode programs)
and WLIB is used for linking Windows/WLO and Mirrors programs.

In the variables RAMDISK, SOURCE, OBJ, OUTPUT, INCLUDE, TMP, RLIB, PLIB und
WLIB you can use the values of environment variables. Enclose their names
in % for this purpose (like in batch files).
Example: INCLUDE=%TMP%\INCLUDE;D:\LIB\INCLUDE;C:\MS\INCLUDE
The %TMP% will be replaced by the value of the environment variable TMP.


5.2. Sections [CS-id]
---------------------

This sections contain the five entries for the environment variables
with the options to be used for them compilers and the linker.

Example:

[CS-STD]
CL=-W3 -Zdep1 -J -G2s -Oxn
CL386=-W3 -Zdep1 -J -Gs -Oxn
PL=-w3 -Zdz
FL=-W1 -Zd -FPi -G2s -Ox
ML=-W2 -Zm -Zd -Zp1 -Cp
MASM=-W2 -Ml -X -Zd
LINK=/BAT /NOIG /NOE


5.3. Sections [CS+ASM], [CS+C], [CS+FOR] and [CS+PAS]
-----------------------------------------------------

In this sections is defined, which include files for the languages
have to be copied to the RAMDISK directory and where they are located
on the harddisk.

Each section may have as much entries as needed. They should have
the format:

FLAGFILE=SOURCE

where FLAGFILE is the name of a file, that is tested for existence in
the RAMDISK before the compiler for this language is called. If it does
not exist in the RAM disk, the file name specification (with wildcards)
in SOURCE is copied to the RAM disk directory. SOURCE has to contain a
full path name.

Example:

[CS+ASM]
DOS.INC=C:\INCLUDE\*.INC
OS2.INC=C:\INCLUDE\OS2\*.INC
MACROS.INC=D:\INCLUDE\*.INC

That means, that CS looks for DOS.INC in the directory specified in the
RAMDISK variable before calling MASM to assemble a source file. If CS does
not find it there, it copies C:\INCLUDE\*.INC to this directory. It is
important, that the SOURCE file pattern matches also for the FLAGFILE
to get this also copied to the RAMDISK. Then further tests will find it
there. If you do not need this feature, leave this sections empty, but
do not delete their [names] and set the RAMDISK variable empty (section 5.1).


6. Other features
-----------------

If the linker encounters any error, its standard input response file
is left as CS.INP in the OUTPUT directory. You may take a look at it
to see if the right options and libraries were specified.

If the linker bundled with the compilers and the assembler is used to
create Windows/WLO applications, you should put the statement
"EXETYPE WINDOWS" into the linker definition file of your program.
The default setting of the normal segmented-executable linker is
"EXETYPE OS2" where the default setting of the version in ther
Windows SDK is "EXETYPE WINDOWS". Windows would not load a program
with "EXETYPE OS2" even if it is a Windows program but this is not
documented in the Microsoft documentation anywhere.

The standard libraries of Microsoft C, Pascal and FORTRAN must have
the machine-mode suffix on their names, i.e. CLIBCER.LIB, CLIBCEP.LIB
and CLIBCEW.LIB instead of CLIBCE.LIB and LIBPASER.LIB, LIBPASEP.LIB
instead of LIBPASE.LIB and MLIBFER.LIB, MLIBFEP.LIB instead of MLIBFORE.LIB
and so on for all memory and floating point models.

Although CS uses the SOURCE variable to look for missing source files,
it may be better to have the current directory set to your sources
because they may include files from this directory without explicit path
name (#include "name.h" in C programs) which the compilers will NOT find
because they do know nothing about the SOURCE variable.

This is required for the Windows resource compiler because it does not
accept full path names.

The resource compiler puts the RES file into the same directory where
the RC file is, not in the OUTPUT directory.

Alternatively to specifying a RC file, a RES file (compiled RC file) is
accepted. This is for users of the Whitewater Ressource Toolkit.

There are two different resource compilers RC.EXE, one for OS/2
Presentation Manager and one for Windows. Make shure that the Windows
one is accessible through the DOS executable search PATH when creating
Windows executables and the OS/2 one is accessible through the OS/2
PATH when creating OS/2 PM executables. For Windows/WLO Programs, the
Windows RC is required. The Windows RC.EXE should be renamed to
RCWIN.EXE. Be sure the correct RCPP.EXE is accessible.


7. Automatic file names
-----------------------

If no names are defined for the output files (EXE, MAP, LST ...)
then CS will create them from the first name passed to it as an argument
but with the correct extension.

If a protected mode program or family mode application is created and
no DEF or BAD file was given, CS looks for a DEF and BAD file with the same
base name as the first file name argument and automatically passed these
files to LINK or BIND if they exist.

If a Windows/WLO or Mirrors program is created and no names of the DEF
or RC files were given, CS looks for them the same way. This applies
also for OS/2 PM programs for the DEF and RC files.

That means, if you call, for example, "CS -AS -LW winprog.c" and there
exist a winprog.def and a winprog.rc file, CS passes winprog.def to
the linker and calls the resource compiler with winprog.rc automatically.

This simplifies the compilation of small programs for which no project
file is needed therefore. You only have to give all related DEF, BAD
and RC files the same base name.

Tho create OS/2 PM programs you have to link with the OS2.LIB import
library instead of the DOSCALLS.LIB import library. This is achieved by
using -LPM instead of -LP or by setting EXETYPE=OS2PM in CS.INI.
The import library and that CS processes a resource file if -LPM is given,
are the only differences between -LP and -LPM and EXETYPE=OS2 and
EXETYPE=OS2PM.


8. Log file
-----------

Sometimes it is useful to keep a protocol of all output of CS and the
called compilers, linker etc. in a log file. This would allow, for example,
to start a big job and the go to lunch and look for all the hundredths
of warnings on return ...
With the -K option, a protocol is written to a file with same base name
and in the same directory as the target executable file but with extension
LOG. All output of the called programs and from CS (produced by -E option,
for example) is duplicated to that file.
Under DOS, this has the disadvantage, that the output from each step
(compiler, linker ...) is only echoed to the display, when the step
finished. Under OS/2, with the -K option, the programs are run through
pipes which are splitted to display and log file. This provides both
immediate screen output and a log file.
A log file is useful in particular, when switching to a higher warning
level for a compiler. This may cause LOTS of warnings on older sources
which can be captured in the log file and read with a text editor later
without beeing without feedback at compilation time (with large programs,
for example, or on slow machines).


9. DLL's
--------

DLL's are most often created with custom memory models like "-Asnu" or
"-ASnw" or "-Alfw" and so on. As the C compiler manual says, are these models
equivalent to "-AS -Au" or "-AS -Aw" and "-AL -Aw" and so on.
That means you should specify one of the standard memory models to CS
and put -Aw or -Au into () with the source files to which they apply.

-Asnw --> -AS -Aw    dto. for -Au
-Asfw --> -AC -Aw
-Alnw --> -AM -Aw
-Alfw --> -AL -Aw

To get CS calling "CL -Asnw -G2s graflib.c", you have to enter
"CS -AS (-Aw -G2s graflib.c)" or write an equivalent project file.

For linking DLL's the option -X is often useful to exclude the
standard libraries ftom the link run.

For DLL's are several extensions used. For Windows EXE, DLL or DRV are used,
for OS/2 is DLL most commonly used. CS allows an extension of DLL alternatively
to EXE on the command line or in project files. For other extensions, rename
the EXE file.

Remember to put the LIBRARY statement into the DEF file instead of the
NAME statement.


10. Exit codes
--------------

CS returns the following exit codes to the caller:

  0 - successful run
  1 - nothing to do (everything was up to date)
  2 - a called program produced an error
      (compiler, assembler, linker ...)
  3 - syntax error in the command line or in a project file
  4 - wrong configuration in CS.INI
  5 - an input file does not exist.
  6 - error in CS.EXE (not enough memory, I/O error ...)

  256 - termination by user (^C, ^BREAK)


11. Restrictions
----------------

- none since version 5 :-)

I don't know other features to put into this program.
Let me know, if you wish to have a new feature ...