home *** CD-ROM | disk | FTP | other *** search
/ Atari FTP / ATARI_FTP_0693.zip / ATARI_FTP_0693 / Mint / mntlib25.zoo / purec / orig / readme
Text File  |  1992-09-30  |  12KB  |  271 lines
  1. MiNT Library for Turbo C / Pure C
  2. ported by:   Ulf Moeller (Ulf_Moeller@hh2.maus.de)
  3.              Michael Hohmuth (hohmuth@freia.inf.tu-dresden.de)
  4. ============================================================================
  5.  
  6. This Michael Hohmuth's version of Ulf Moeller's port. The description of
  7. the installation follows after Ulf's opening words:
  8.  
  9. ----------------------------------------------------------------------------
  10. This is a port of Eric Smith's MiNT library for Turbo C and Pure C.
  11. The assembler files are partly based on Dave Gymer's Sozobon port. The
  12. MiNT library replaces the functions of PCSTDLIB. For floating point support,
  13. you must still use the Pure C libraries.
  14.  
  15. I have not fully tested the library, and of course there is no warranty
  16. for whatsoever. Since there is a number of major differences between GNU C
  17. and Pure C, bugs are not really improbable. What is true for the Sozobon
  18. version, applies to this one even more: "is very experimental and quite
  19. probably needs more work; caveat emptor."
  20. ----------------------------------------------------------------------------
  21.  
  22. INSTALLATION.
  23. -------------
  24.  
  25. [Parts of the following description are derived from Ulf's README.]
  26.  
  27. Create Your Environment.
  28.  
  29. 0)  Don't delete the Sozobon C support directory. A few C sources of this
  30.     directory are used.
  31.  
  32. 1)  Create a copy of the file PC.CNF resp. TC.CNF in the Pure/Turbo C
  33.     directoy, named MINTLIB.CNF
  34.  
  35. 2)  Copy the files math.h and float.h from the Pure/Turbo C include directory
  36.     to the MiNT library include directory, naming them tcmath.h resp.
  37.     tcfloat.h
  38.  
  39. 3)  Only for Turbo C: 
  40.     =================
  41.     o   Delete the assembler options for setjmp.s and alloca.s in the files 
  42.         mintlib.prj and test.prj; remove the semicolon in front of the 
  43.         symbol definitions in the corresponding source files.
  44.  
  45.     o   Comment out the line 
  46.         "falloca.s [-O=falloca -DSTACK_CHECKING=1 -DFPU=1]"
  47.         in test.prj.
  48.  
  49.     o   Comment out pclong.s in mintlib.prj. (You'll have to link the standard 
  50.         library tcstdlib.lib for long int arithmetics support in your project
  51.         files.)
  52.  
  53.     o   For the GEMDOS/MiNT bindings that have to be linked to the MiNT 
  54.         library, you have two choices:
  55.         
  56.         a) I'd strongly suggest you to get the osbind library by Ole Arndt and
  57.         Ulf Moeller. It replaces all functions of the tctoslib.lib, with a few
  58.         slight enhancements, and contains all MiNT bindings.
  59.         List osbind.prj in mintlib.prj, and comment out pctoslib.lib and 
  60.         mintbind.s.
  61.  
  62.         b) If you don't have the osbind library, you can do the following:    
  63.         In mintlib.prj, change the file name pctoslib.lib to tctoslib.lib.
  64.         Look over mintbind.s. Delete all instances of the strings ".MODULE"
  65.         and ".ENDMOD". (MAS, the assembler that comes with Turbo C, doesn't 
  66.         understand them.)
  67.         Disadvantage: All MiNT bindings in mintbind.s get linked to your
  68.         programs in their entirety if you (or other library functions) use
  69.         any MiNT binding at all.
  70.  
  71.     o   In mintflt.prj, change the file name pcfltlib.lib to tcfltlib.lib.
  72.  
  73. 4)  Start C, load mintlib.cnf and set the include directory to the the 
  74.     directory where the MiNT library's include files reside. In the 
  75.     Options/Shell dialog, turn off "Make breaks on compiler warnings".
  76.     With Pure C, turning on the compiler caches speeds up the Make procedure
  77.     dramatically.
  78.     If you want debug information in the libraries, set the compiler switch
  79.     -Y (Options/Compiler, Options/Assembler and Options/Linker).
  80.  
  81. Make The Floating Point Library.
  82.  
  83. This library contains the float/double support for the compiler as well as
  84. versions of printf/scanf that support floating point numbers.
  85.  
  86. 5)  Select the project file MINTFLT.PRJ. Make all.
  87.  
  88. 5a) You have to delete the files main.o, doprnt.o, scanf.o, difftime.o and
  89.     purec/setjmp.o now. These files have to be recompiled with the Line-F 
  90.     support (step 6) and the main part of the MiNT library (step 7).
  91.  
  92. Make The Line-F Support Library. (Pure C only)
  93.  
  94. This library contains actually the same as the floating point library, plus
  95. support for programs that use a FPU directly via Line-F.
  96.  
  97. 6)  Only for Pure C:
  98.     ================
  99.     Repeat steps 5 and 5a with MINT881.PRJ.
  100.  
  101. Make The MiNT Library.
  102.  
  103. 7)  Select the project file MINTLIB.PRJ. Make all.
  104.     This step takes a while (around 15 minutes with Pure C and an 8MHz ST).
  105.     (But compared to the time GNU C needs to make the library -- you'll
  106.     love it! :-)
  107.  
  108. Compile The Startup Code And The Assembler Version Of alloca();
  109. Test The Libraries.
  110.  
  111. 8)  Select the project file TEST.PRJ. Make all.
  112.     This compiles the startup code and the assembler versions of alloca(),
  113.     and links a test program.
  114.     
  115.     (Pure C: You get a linker warning "Doubly defined symbol: 'alloca'"
  116.     because alloca.s and falloca.s both define a symbol `alloca'. Ignore it.)
  117.  
  118. 9)  Run. You should get a "Hello, world." message.
  119.  
  120. Install The Libraries.
  121.  
  122. 10) Copy the files crt0.o, alloca.o, mintlib.lib, mintflt.lib, falloca.o and
  123.     mint881.lib (the last two are Pure C only) to the directory you want them
  124.     to reside.
  125.  
  126.  
  127. USAGE.
  128. ------
  129.  
  130. If you want to use the MiNT library for your project, consider the following:
  131.  
  132. General Usage.
  133.  
  134. o   Make sure that the include directory (Options/Compiler) is set to the 
  135.     directory where the include files of the MiNT library reside, and that
  136.     the libraries directory is set to the directory you copied the objects
  137.     to (step 10).
  138.     
  139. o   Use crt0.o as your startup code.
  140.  
  141. o   List mintlib.lib in your project file. This replaces the library
  142.     pctoslib.lib (resp. tctoslib.lib). You can still use pcextlib.lib
  143.     (tcextlib.lib) for backward compatibelity, but you probably don't want
  144.     to. The pcstdlib.lib library you only need if you want to use floating 
  145.     point arithmetics in your program (see below). For GEM and BGI graphics, 
  146.     you can still use pcgemlib.lib and pcbgilib.lib. (Be careful with the GEM 
  147.     library; I have not yet checked whether the header files of the MiNT 
  148.     library are conform with the library.)
  149.  
  150. o   Two simple project files are delivered with the library. You can use
  151.     them as a reference when creating your own project files:
  152.  
  153.     default.prj  - compiles the topmost window with float support
  154.     tc-deflt.prj - dito, for Turbo C
  155.     idefault.prj - compiles the topmost window without float support
  156.     tc-idflt.prj - dito, for Turbo C
  157.  
  158. Float Support.
  159.  
  160. o   The library file mintlib.lib does not contain float support for 
  161.     Pure/Turbo C. If you want to use floating point numbers in your program, 
  162.     you'll have to link mintflt.lib and pcstdlib.lib (which also contains 
  163.     some float support). List mintflt.lib BEFORE mintlib.lib and pcstdlib.lib
  164.     AFTER mintlib.lib in your project file (tc* versions respectively).
  165.  
  166. Turbo C Caveats.
  167.  
  168. o   When used with Turbo C, you'll always have to link tcstdlib.lib. It 
  169.     contains the long arithmetics support for the compiler. List tcstdlib.lib
  170.     AFTER mintlib.lib in your project file.
  171.  
  172. FPU Support.
  173.  
  174. o   Pure C: For real (i.e. Line-F) FPU support, replace mintflt.lib by 
  175.     mint881.lib and use the appropriate compiler flag (-8) to compile your
  176.     project. 
  177.     
  178.     If you want to use the assembler version of alloca() in your program (see
  179.     below), replace alloca.o by falloca.o in your project file.
  180.  
  181. o   Turbo C: The Turbo C libraries don't support FPUs via Line-F. You might 
  182.     want to try Peter Fiebelkorn's FPUPATCH: Apply the patch to your original
  183.     Turbo C libraries and use the resulting tcflt.lib instead of tcfltlib.lib 
  184.     in the library's mintflt.prj, and use tcstd.lib instead of tcstdlib.lib 
  185.     in your project file.
  186.  
  187. The Stack.
  188.  
  189. o   The Pure/Turbo Linker usually reserves stack space in the BSS. If you
  190.     set stack size 0 for the linker, the MiNT library will use the usual
  191.     convention of setting the stack by _stksize (default: 8k); see crtinit.c
  192.     for details.
  193.  
  194. o   The stack checking option does not work with threads, or with malloc
  195.     from heap.
  196.  
  197. o   Implementation Note: crtinit.c and the parts of the MiNT library that 
  198.     are executed during abnormal program termination must not be compiled 
  199.     with stack checking set. With the assembler option -DSTACK_CHECKING=0 or 
  200.     1, you can control if alloca checks whether there is enough stack space 
  201.     for it.
  202.  
  203. Using alloca().
  204.  
  205. o   The alloca() function is a certain problem for Pure/Turbo C. The library
  206.     contains a slow-but-secure version of alloca(). You can also link the
  207.     the (fast) assembler version of alloca() (by listing alloca.o [resp. 
  208.     falloca.o, see "FPU Support" above] BEFORE mintlib.lib in your project 
  209.     file). This version only works if the caller was compiled with option -S 
  210.     (Options/Compiler/Standard Stack Frames). Otherwise, it will destroy the 
  211.     stack and the program will crash.
  212.  
  213. Use Prototypes!
  214.  
  215. o   Giving prototypes is important for Pure C. They are absolutely necessary
  216.     for functions with a variable argument list (e. g. error() in the GNU
  217.     file utilities).
  218.  
  219. How To Include Files From Subdirectories?
  220.  
  221. o   Pure/Turbo C does not understand e.g. #include <sys/dir.h>. It tries to
  222.     open a file 'sys/dir.h' in the current directory instead of the file
  223.     'dir.h' in the subdirectory 'sys'. Therefore you either have to use 
  224.     #include <sys\dir.h>, or you use the program unixname.prg by Michael
  225.     Schwingen that is shipped with this library: Simply move it to your AUTO 
  226.     folder, or run it from the desktop before you start C. When installed, 
  227.     it converts all slashes to backslashes automagically when accessing disk 
  228.     files. 
  229.     
  230.     I have no docs for unixname.prg, so here's a short description:
  231.  
  232.     When used with MiNT, unixname.prg works best when run after MiNT. Note
  233.     that it only converts file names that are passed as parameters to a 
  234.     standard GEMDOS calls; it does not convert file names passed to a MiNT 
  235.     system call. (However, MiNT aware programs should be aware of slashes in 
  236.     any case.) WARNING: This program modifies the file name in the caller's
  237.     address space. With this program installed you cannot any longer use
  238.     files that contain slashes in their base name.
  239.  
  240.     To make the library you don't nessecarily have to install unixname.prg.
  241.  
  242. Before...
  243.  
  244. ...you try the PS from the MiNT utilities, change this:
  245. 178c178
  246. <     printf("%03d  %03d %3d   %3d  %s  %8ld %02d:%02d.%02d  %s%s\n",
  247. ---
  248. >     printf("%03d  %03d %3d   %3d  %s  %8ld %02ld:%02ld.%02ld  %s%s\n",
  249.  
  250.  
  251. LEGAL NOTICE.
  252. -------------
  253.  
  254. The library binaries mintlib.lib, mintflt.lib and mint881.lib, when built
  255. with the setup as shipped, will contain Turbo/Pure C's library binaries.
  256. Don't make these binaries available to the public, always ship this library
  257. in source form.
  258.  
  259. ----------------------------------------------------------------------------
  260.  
  261. If you want to contact me, here are my addresses:
  262.  
  263. --
  264. Email:
  265.     Internet:   hohmuth@freia.inf.tu-dresden.de     [preferred]
  266.                 mh1@irz301.inf.tu-dresden.de        [if the other one
  267.                                                      doesn't work]
  268. IRC:
  269.     Nickname:   Spell
  270.     You can drop me a note at NoteServ.
  271.