Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / proglang / cs56.arj / ENGLISH.DOC < prev next >

Wrap

Text File | 1990-10-15 | 24.8 KB | 615 lines

CS 5.6 - Compiler Shell - (c) Kai Uwe Rommel - Sep 30 1990 1. Introduction --------------- CS is a driver program or shell for the following Microsoft program development tools: - Macro Assembler (5.00 and newer) - C Compiler (5.00 and newer, 6.00 is supported) - Pascal Compiler (4.00 and newer) - FORTRAN Compiler (4.00 and newer) - Windows Resource Compiler (2.00 and newer) - OS/2 Resource Compiler - LINK (5.00 and newer) - ILINK - BIND - EXE2BIN - CVPACK - LIB (3.08 and newer) - CREF - 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 system-wide TOOLS.INI file (the file used by the Microsoft Editor and the MAKE and NMAKE programs for their configuration data). All configuration data for CS itself is also held in TOOLS.INI. CS is a family mode application and runs under MS-DOS and under OS/2 in both real and protected mode. The following files can be produced from your sources using CS: a) real mode programs - DOS EXE format - DOS COM format - DOS Windows EXE format (including DLL's) b) protected mode programs - OS/2 EXE format (including DLL's and Presentation Manager programs) - Bound EXE format (family applications for OS/2 and DOS) (The creation of programs for the Presentation Manager differs from creation of standard OS/2 applications only in that another import library, OS2.LIB, is used instead of DOSCALLS.LIB). c) linker maps d) listings e) 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 -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 TOOLS.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 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) To specify additional API libraries for BIND instead for LINK (they have the same extension), append an exclamation mark directly to the name of the library to distinguish it from LINK libraries. CS looks for BIND API libraries through the PLIB 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. 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. -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 -> Real-Mode-Windows-EXE -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 -FA Alternate floating point library. library used ! -FD Decimal arithmetics (only for Pascal). -Oid The id selects the section in TOOLS.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. -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). -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 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. TOOLS.INI ------------ The characteristics of your system needed for CS have to be configured in the system-wide file TOOLS.INI. This file must be accessible through environment variables INIT or PATH. It is also used by the Microsoft Editor and MAKE and NMAKE programs, so you may be familiar with this file and its format. 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 CS.INI. You can append this file to your TOOLS.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 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, ALTERNATE or DECIMAL. Equivalent to -Ff option. OPTIONS=<id> Specifies the name of the TOOLS.INI section with the default compiler and linker options. Equivalent to -Oid option. 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. 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. 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. 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> 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. RLIB=<pathlist> PLIB=<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 and WLIB is used for linking Windows 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 PL=-w3 -Zdz FL=-W1 -Zd -FPi -G2s -Ox 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 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". This is only needed for programs without resources, because the resource compiler corrects the type otherwise. 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. 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. 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 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 TOOLS.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 TOOLS.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 ...