home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / CS46.ZIP / ENGLISH.DOC < prev    next >
Text File  |  1990-07-17  |  22KB  |  524 lines
  1. CS 4.6 - Compiler Shell - (c) Kai Uwe Rommel - Mar 27 1990
  2.  
  3.  
  4. 1. Introduction
  5. ---------------
  6.  
  7. CS is a driver program or shell for the Microsoft Macro Assembler
  8. (5.00 and above), the C Compiler (5.00 and above), Pascal Compiler
  9. (4.00 and above), FORTRAN Compiler (4.00 and above), the Windows
  10. Resource Compiler (2.00 and above), the OS/2 PM Resource Compiler
  11. and the utility programs LINK (5.00 and above), ILINK, BIND, EXE2BIN,
  12. CVPACK, LIB (3.08 and above) and CREF.
  13.  
  14. CS simplifies the usage of this programs and preserves you from
  15. typing of often used options and commands, looks for files in configured
  16. directories and calls your compiler(s) with a MAKE-like strategy.
  17.  
  18. You do not have to create a complicated description of all dependencies
  19. and commands in a makefile. Instead, you write the names of all input
  20. files of a project into a CS project file (see below) together with
  21. some options or enter them directly on the command line (depending of
  22. the size of your project). CS detects the file types from the extension
  23. of their names and automatically knows, what it has to do with them,
  24. call a compiler, add them to the LINK or BIND command and so on.
  25. It also knows from the file dates which files are out of date and have
  26. to be recompiled and which files are up to date. This is similar to the
  27. strategy of the MAKE program. Another feature of CS is, that it allows
  28. you to maintain sets of often used options for the compilers and the
  29. linker in sections of the system-wide TOOLS.INI file (the file used
  30. by the Microsoft Editor and the MAKE and NMAKE programs for their
  31. configuration data). All configuration data for CS itself is also
  32. held in TOOLS.INI.
  33.  
  34. CS is a family mode application and runs under MS-DOS and under OS/2
  35. in both real and protected mode.
  36.  
  37. The following files can be produced from your sources using CS:
  38.  
  39. a) real mode programs
  40.    - DOS EXE format
  41.    - DOS COM format
  42.    - DOS Windows EXE format (including DLL's)
  43.  
  44. b) protected mode programs
  45.    - OS/2 EXE format (including DLL's and Presentation Manager programs)
  46.    - Bound EXE format (family applications for OS/2 and DOS)
  47.  
  48.    (The creation of programs for the Presentation Manager differs from
  49.    creation of standard OS/2 applications only in that another import
  50.    library, OS2.LIB, is used instead of DOSCALLS.LIB).
  51.  
  52. c) linker maps
  53.  
  54. d) listings
  55.  
  56. e) object libraries
  57.  
  58.  
  59. 2. Syntax
  60. ---------
  61.  
  62. Usage:  CS argument*
  63.  
  64.         argument  = globalopt | fileset
  65.         fileset   = filespec  | '(' item* ')'
  66.         item      = localopt  | filespec
  67.         filespec  = filename  | filename '{' include* '}'
  68.         include   = filename
  69.  
  70. Where:  globalopt ε { -? -H -Am -Ff -Le -Sn -Oid
  71.                       -C -L -E -N -B -I -X -P -M -LS -NS -NF }
  72.  
  73.         m         = model identifier S, M, C, L, H or MT
  74.         f         = float type identifier E, 7, A or D
  75.         e         = program type identifier R, C, P, PM, B, W or L
  76.         id        = name of TOOLS.INI section with compiler options
  77.         n         = stack size in bytes (decimal or hex with prefix 0x)
  78.  
  79.         filename  = any DOS file name, all names in a fileset in ()
  80.                     must have the same extension (C, PAS, FOR or ASM)
  81.         localopt  = any valid option for the compiler associated with
  82.                     the extension of the files in the fileset.
  83.  
  84. Input files can have the extensions C, PAS, FOR, ASM, OBJ, LIB or RC
  85. or DEF (linker definition file), BAD (list for BIND of symbols to be
  86. bound to BadDynLink) or CS (CS project file).
  87.  
  88. To specify additional API libraries for BIND instead for LINK (they
  89. have the same extension), append an exclamation mark directly to the
  90. name of the library to distinguish it from LINK libraries. CS looks
  91. for BIND API libraries through the PLIB variable (see section 5.1).
  92.  
  93. If there are special options for one ore more source files to the compiler
  94. associated with their type, they can be enclosed with the files for
  95. which they should be used in parentheses. For all filesets enclosed
  96. in () the compiler is called separately (normally, the compilers are
  97. called with as much file names as arguments as fit on the command line,
  98. for those compilers that support multiple file arguments, namely CL and FL).
  99.  
  100. To help CS to handle more complicated dependencies, one or more files
  101. can be associated with each source file, which depends on them. This is
  102. often useful for include or header files. All names of files on which
  103. a particular source file depends, must be enclosed in curly brackets {}
  104. and follow the source file immediately. This files are used ONLY for
  105. the MAKE-strategy, i.e. to determine if a source file has to be recompiled
  106. or not.
  107.  
  108. If there are files given on the command line or in the project file
  109. with extensions EXE, DLL, COM, MAP or LST, then this names define the
  110. names of the output files and define their type (EXE/COM/DLL) or cause
  111. their production (MAP, LST) if given. That means, if you give the names
  112. FOO.COM and BAR.MAP as arguments to CS, it will try to compile the source
  113. files to a DOS COM program named FOO.COM and it will tell LINK to write
  114. a link map to the file BAR.MAP.
  115.  
  116. Example:
  117. CS -lp main.c{def.h} prog.exe (mod1.c mod2.c -Gt) mod3.asm mod4.c mod5.pas
  118.  
  119. (If this appears to be cryptical of difficult to type, this shows the
  120. usefulness of CS project files, see the equivalent project file below.)
  121.  
  122. Wildcard expansion is supported, with the restriction, that names containing
  123. wildcards have to be separated with blanks from the context on both sides.
  124.  
  125. Wrong:  CS haupt.c (mod*.c -G2)
  126. Right:  CS haupt.c ( mod*.c -G2)
  127.  
  128.  
  129. 3. CS project files
  130. -------------------
  131.  
  132. If CS encounters any file with extension CS in its arguments, the
  133. contents of the file is read and evaluated if it was given as arguments.
  134. The text read from the file is logically placed on the command line
  135. instead of the file name. These files are called PROJECT FILES.
  136. They can have any number of lines but must not contain wildcards
  137. in filenames listed in them.
  138.  
  139. The extension CS of project files can be omitted. This is the ONLY
  140. type of file known to CS of which the extension is optional. That means
  141. you only have to enter "CS foo" if FOO.CS exists in the current directory
  142. or in any directory listed in the SOURCE variable (see below).
  143.  
  144. For better readability, the text of a project file can (should) be
  145. written on multiple lines. Lines starting with ; or # are treated as
  146. comment lines and are ignored up to the next line feed.
  147.  
  148. CS project files are intended for bigger projects which consist of
  149. many files and more complicated dependency trees or special options.
  150. The usage of () and {} on the command line is not very comfortable,
  151. for projects which require their usage, you will probably use
  152. project files.
  153.  
  154. Such a project file is MUCH shorter and easier to wite than a makefile.
  155. For programs like GNU awk or perl (widely used freeware programs) the
  156. makefiles are 100 or more lines long but the equivalent CS project files
  157. fit into 10 lines. Also, they require less "debugging".
  158.  
  159. The project file for the sample command line above could look like:
  160.  
  161. ; Project: xyz
  162. ; Date:   1.4.1989
  163. ;
  164. ; main module
  165. main.c {def.h}
  166. ;
  167. ; subroutines with special options
  168. (mod1.c mod2.c -Gt)
  169. ;
  170. ; other subroutines
  171. mod3.asm
  172. mod4.c
  173. mod5.pas
  174. ;
  175. ; output file name for family mode application
  176. prog.exe -lb
  177.  
  178. If CS is called without any arguments or the arguments to CS do not
  179. contain any file name of a source file with extension C, PAS, FOR, ASM or
  180. OBJ, it looks fo a file PROJECT.CS in the current directory. If it
  181. exists it is read as if it was given to CS as an argument. This makes
  182. the functionality of PROJECT.CS almost like "makefile" for the standard
  183. make utility.
  184.  
  185.  
  186. 4. Options
  187. ----------
  188.  
  189. -Am     Defines the memory model for C, FORTRAN and MASM. To MASM, the
  190.         model is passed as "-Dmodel=small" etc. which requires your
  191.         sources to contain a statement like "% .MODEL model" at the very
  192.         beginning of the text if you want to choose the memory model at
  193.         compile time for assembler programs.
  194.         For m the letters S, M, C, L, H and MT are valid. MT stands for
  195.         the custom model for multithreaded OS/2 programs with LLIBCMT.LIB.
  196.  
  197. -Le     Defines the output format of the linker (e = R, C, W, P, PM, B oder L).
  198. -LR     -> Real-Mode-EXE for DOS
  199. -LC     -> Real-Mode-COM for DOS
  200. -LW     -> Real-Mode-Windows-EXE
  201. -LP     -> Protected-Mode-EXE for OS/2 (without Presentation Manager)
  202. -LPM    -> Protected-Mode-EXE for OS/2 (with Presentation Manager)
  203. -LB     -> Bound-EXE
  204. -LL     -> LIB is used instead of LINK to create an object library
  205.            where the object modules of all sources are put.
  206.  
  207. -Ff     Defines the type of the floating point arithmetics.
  208. -FE     Floating point with emulator.                    This also influences
  209. -F7     Floating point with 80x87 coprocessor.           the type of standard
  210. -FA     Alternate floating point library.                library used !
  211. -FD     Decimal arithmetics (only for Pascal).
  212.  
  213. -Oid    The id selects the section in TOOLS.INI with the compiler options
  214.         to be used. CS looks for a section named [CS-id]. From this section
  215.         the values for the environment variables CL, PL, FL, MASM and LINK
  216.         are read. The id should be 15 characters or less in length.
  217.  
  218. -Sn     Defines the stack size for the linker. It can be entered decimal
  219.         or hex with the prefix 0x (standard C notation).
  220.  
  221. -C      Compile only.
  222.  
  223. -L      Link only.
  224.  
  225. -E      Echo all commands before executing them.
  226.  
  227. -N      No execution of commands, only show them.
  228.  
  229. -B      Don't use MAKE strategy, build all files regardless of file dates.
  230.  
  231. -X      Link without standard libraries.
  232.  
  233. -I      Link incrementally with ILINK whenever possible (see below).
  234.  
  235. -P      Call CVPACK if the output executable contains debugging information.
  236.  
  237. -M      Create a linker map and, if -LB is used, also a binder map.
  238.  
  239. -LS     Create compiler listings.
  240.  
  241. -NF     Use full qualified path names when passing names of source files
  242.         to the compilers. This is useful when using CodeView because it
  243.         can always find the source files even if they are not in the
  244.         current directory.
  245.  
  246. -NS     Opposite of above option. Use simple file names whenever posible
  247.         except for the source files located via SOURCE variable.
  248.  
  249.  
  250. 5. TOOLS.INI
  251. ------------
  252.  
  253. The characteristics of your system needed for CS have to be configured
  254. in the system-wide file TOOLS.INI. This file must be accessible through
  255. environment variables INIT or PATH. It is also used by the Microsoft
  256. Editor and MAKE and NMAKE programs, so you may be familiar with this file
  257. and its format. It is similar in its format to WIN.INI of Microsoft
  258. Windows. Each program that knows about it can create sections denoted
  259. with "[name]" and store data in it in "name=value" or "name:value" formats.
  260. That makes it ideal as a system-wide database for initialization and
  261. configuration information. The OS2.INI file is an extension of this
  262. method but uses a binary format not readable by humans.
  263. See the sample configuration in CS.INI. You can append this file to your
  264. TOOLS.INI and modifiy the setting for your needs.
  265.  
  266.  
  267. 5.1. Section [CS]
  268. -----------------
  269.  
  270. In this section various default values for CS are specified that can
  271. be overridden by command line options or project files.
  272.  
  273. MODEL=<model>
  274. Valid models are SMALL, MEDIUM, COMPACT, LARGE, HUGE or MTHREAD.
  275. This defines the default memory model if no -Am option is used on the
  276. CS command line or in a project file. Equivalent to -Am option.
  277.  
  278. EXETYPE=<type>
  279. Valid types are DEFAULT, DOS, COM, OS2, OS2PM, BOUND, WINDOWS or LIBRARY.
  280. If DEFAULT is specified, depending on the machine mode either DOS or OS2
  281. is choosen automatically. When LIBRARY is used, all object modules are
  282. written to an object library with LIB and no EXE file is created.
  283. Equivalent to -Le option.
  284.  
  285. FLOAT=<type>
  286. Valid types are EMULATOR, 80X87, ALTERNATE or DECIMAL.
  287. Equivalent to -Ff option.
  288.  
  289. OPTIONS=<id>
  290. Specifies the name of the TOOLS.INI section with the default compiler
  291. and linker options. Equivalent to -Oid option.
  292.  
  293. STACK=<size>
  294. Defines the default stack size for LINK. Equivalent to -Sn option.
  295.  
  296. ILINK=<options>
  297. Defines the options to be used for link in order to prepare an executable
  298. file for incremental linking (seem ILINK manual). It should contain
  299. /PADC:x and /PADD:y options but not the /INC option. Set x and y after
  300. your personal requirements. No command line equivalent.
  301.  
  302. NAMES=FULL or NAMES=SHORT
  303. Equivalent to -NF and -NS command line options (see above). This
  304. specifies default behaviour, if none of the both command line options
  305. is used.
  306.  
  307. BUILD=NO or BUILD=YES
  308. The setting BUILD=YES disables the MAKE strategy of CS. Normally,
  309. BUILD=NO should be used. See -B command line option.
  310.  
  311. RAMDISK=<path>
  312. If a nonempty path is specified that points into a RAM disk, then some
  313. header or include files for the compilers to be called later are copied
  314. to this directory if they are not already there. This can reduce harddisk
  315. access considerably. List the path in your INCLUDE variable too (see below).
  316. See section 4.3.
  317.  
  318. SOURCE=<pathlist>
  319. You can define several directories in PATH syntax which are searched
  320. for source files that were specified on the command line or in a project
  321. file but do not exist in the current directory. CS searches using this
  322. variable for file of types ASM, C, PAS, FOR, DEF, BAD and CS.
  323.  
  324. OBJ=<pathlist>
  325. Same purpose as SOURCE but used to search for object files.
  326.  
  327. OUTPUT=<path>
  328. Specifies the output directory for all files created by the programs
  329. called by CS. Best is to let it point to a big RAM disk. If you want to
  330. override this setting on the command line or in a project file,
  331. include drives or paths to the file names.
  332.  
  333. INCLUDE=<pathlist>
  334. TMP=<path>
  335. These variables specify the values of the environment variables with
  336. the same names that are set before the compilers and the linker are called.
  337.  
  338. RLIB=<pathlist> 
  339. PLIB=<pathlist> 
  340. WLIB=<pathlist>
  341. These variables define the value of the LIB environment variable for
  342. the linker. RLIB is used when real mode programs (EXE or COM) are created,
  343. PLIB is used when protected mode programs (with or without PM and bound
  344. programs) are created and WLIB is used for linking Windows programs.
  345.  
  346.  
  347. 5.2. Sections [CS-id]
  348. ---------------------
  349.  
  350. This sections contain the five entries for the environment variables
  351. with the options to be used for them compilers and the linker.
  352.  
  353. Example:
  354.  
  355. [CS-STD]
  356. CL=-W3 -Zdep1 -J -G2s -Oxn
  357. PL=-w3 -Zdz
  358. FL=-W1 -Zd -FPi -G2s -Ox
  359. MASM=-W2 -Ml -X -Zd
  360. LINK=/BAT /NOIG /NOE
  361.  
  362.  
  363. 5.3. Sections [CS+ASM], [CS+C], [CS+FOR] and [CS+PAS]
  364. -----------------------------------------------------
  365.  
  366. In this sections is defined, which include files for the languages
  367. have to be copied to the RAMDISK directory and where they are located
  368. on the harddisk.
  369.  
  370. Each section may have as much entries as needed. They should have
  371. the format:
  372.  
  373. FLAGFILE=SOURCE
  374.  
  375. where FLAGFILE is the name of a file, that is tested for existence in
  376. the RAMDISK before the compiler for this language is called. If it does
  377. not exist in the RAM disk, the file name specification (with wildcards)
  378. in SOURCE is copied to the RAM disk directory. SOURCE has to contain a
  379. full path name.
  380.  
  381. Example:
  382.  
  383. [CS+ASM]
  384. DOS.INC=C:\INCLUDE\*.INC
  385. OS2.INC=C:\INCLUDE\OS2\*.INC
  386. MACROS.INC=D:\INCLUDE\*.INC
  387.  
  388. That means, that CS looks for DOS.INC in the directory specified in the
  389. RAMDISK variable before calling MASM to assemble a source file. If CS does
  390. not find it there, it copies C:\INCLUDE\*.INC to this directory. It is
  391. important, that the SOURCE file pattern matches also for the FLAGFILE
  392. to get this also copied to the RAMDISK. Then further tests will find it
  393. there. If you do not need this feature, leave this sections empty, but
  394. do not delete their [names] and set the RAMDISK variable empty (section 5.1).
  395.  
  396.  
  397. 6. Other features
  398. -----------------
  399.  
  400. If the linker encounters any error, its standard input response file
  401. is left as CS.INP in the OUTPUT directory. You may take a look at it
  402. to see if the right options and libraries were specified.
  403.  
  404. If the linker bundled with the compilers and the assembler is used to
  405. create Windows applications, you should put the statement "EXETYPE WINDOWS"
  406. into the linker definition file of your program. The default setting of
  407. the normal segmented-executable linker is "EXETYPE OS2" where the default
  408. setting of the version in ther Windows SDK is "EXETYPE WINDOWS".
  409. This is only needed for programs without resources, because the
  410. resource compiler corrects the type otherwise. Windows would not load
  411. a program with "EXETYPE OS2" even if it is a Windows program but this
  412. is not documented in the Microsoft documentation anywhere.
  413.  
  414. The standard libraries of Microsoft C, Pascal and FORTRAN must have
  415. the machine-mode suffix on their names, i.e. CLIBCER.LIB, CLIBCEP.LIB
  416. and CLIBCEW.LIB instead of CLIBCE.LIB and LIBPASER.LIB, LIBPASEP.LIB
  417. instead of LIBPASE.LIB and MLIBFER.LIB, MLIBFEP.LIB instead of MLIBFORE.LIB
  418. and so on for all memory and floating point models.
  419.  
  420. Although CS uses the SOURCE variable to look for missing source files,
  421. it may be better to have the current directory set to your sources
  422. because they may include files from this directory without explicit path
  423. name (#include "name.h" in C programs) which the compilers will NOT find
  424. because they do know nothing about the SOURCE variable.
  425.  
  426. This is required for the Windows resource compiler because it does not
  427. accept full path names.
  428.  
  429. The resource compiler puts the RES file into the same directory where
  430. the RC file is, not in the OUTPUT directory.
  431.  
  432. The windows resource compiler has to be renamed to RW.EXE to distinguish
  433. it from the OS/2 PM resource compiler which has the same name RC.EXE as
  434. the Windows one. If both resource compilers for Windows and OS/2 presentation
  435. manager are used on the same system, the preprocessor RCPP.EXE of the windows
  436. version should also be renamed to RWPP.EXE and its name has to be patched
  437. in RW.EXE or your should put it into a different directory and have
  438. different PATH settings on DOS and OS/2.
  439.  
  440.  
  441. 7. Automatic file names
  442. -----------------------
  443.  
  444. If no names are defined for the output files (EXE, MAP, LST ...)
  445. then CS will create them from the first name passed to it as an argument
  446. but with the correct extension.
  447.  
  448. If a protected mode program or family mode application is created and
  449. no DEF or BAD file was given, CS looks for a DEF and BAD file with the same
  450. base name as the first file name argument and automatically passed these
  451. files to LINK or BIND if they exist.
  452.  
  453. If a Windows program is created and no names of the DEF or RC files were
  454. given, CS looks for them the same way. This applies also for OS/2 PM
  455. programs for the DEF and RC files.
  456.  
  457. That means, if you call, for example, "CS -AS -LW winprog.c" and there
  458. exist a winprog.def and a winprog.rc file, CS passes winprog.def to
  459. the linker and calls the resource compiler with winprog.rc automatically.
  460.  
  461. This simplifies the compilation of small programs for which no project
  462. file is needed therefore. You only have to give all related DEF, BAD
  463. and RC files the same base name.
  464.  
  465. Tho create OS/2 PM programs you have to link with the OS2.LIB import
  466. library instead of the DOSCALLS.LIB import library. This is achieved by
  467. using -LPM instead of -LP or by setting EXETYPE=OS2PM in TOOLS.INI.
  468. The import library and that CS processes a resource file if -LPM is given,
  469. are the only differences between -LP and -LPM and EXETYPE=OS2 and
  470. EXETYPE=OS2PM.
  471.  
  472.  
  473. 8. DLL's
  474. --------
  475.  
  476. DLL's are most often created with custom memory models like "-Asnu" or
  477. "-ASnw" or "-Alfw" and so on. As the C compiler manual says, are these models
  478. equivalent to "-AS -Au" or "-AS -Aw" and "-AL -Aw" and so on.
  479. That means you should specify one of the standard memory models to CS
  480. and put -Aw or -Au into () with the source files to which they apply.
  481.  
  482. -Asnw --> -AS -Aw    dto. for -Au
  483. -Asfw --> -AC -Aw
  484. -Alnw --> -AM -Aw
  485. -Alfw --> -AL -Aw
  486.  
  487. To get CS calling "CL -Asnw -G2s graflib.c", you have to enter
  488. "CS -AS (-Aw -G2s graflib.c)" or write an equivalent project file.
  489.  
  490. For linking DLL's the option -X is often useful to exclude the
  491. standard libraries ftom the link run.
  492.  
  493. For DLL's are several extensions used. For Windows EXE, DLL or DRV are used,
  494. for OS/2 is DLL most commonly used. CS allows an extension of DLL alternatively
  495. to EXE on the command line or in project files. For other extensions, rename
  496. the EXE file.
  497.  
  498. Remember to put the LIBRARY statement into the DEF file instead of the
  499. NAME statement.
  500.  
  501.  
  502. 9. Exit codes
  503. -------------
  504.  
  505. CS returns the following exit codes to the caller:
  506.  
  507.   0 - successful run
  508.   1 - nothing to do (everything was up to date)
  509.   2 - a called program produced an error
  510.       (compiler, assembler, linker ...)
  511.   3 - syntax error in the command line or in a project file
  512.   4 - wrong configuration in TOOLS.INI
  513.   5 - an input file does not exist.
  514.   6 - error in CS.EXE (not enough memory, I/O error ...)
  515.  
  516.   256 - termination by user (^C, ^BREAK)
  517.  
  518.  
  519. 10. Restrictions
  520. ----------------
  521.  
  522. - none since version 4.3 :-)
  523.   except that BISON and FLEX parser/scanner generators are not yet supported
  524.