home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / cbm / nduk-v40.lha / V40 / Using_Includes < prev    next >
Text File  |  1994-02-13  |  10KB  |  257 lines
  1.  
  2. Using 3.x Amiga Includes and Libs
  3. =================================
  4. (c) Copyright 1993 Commodore-Amiga, Inc.  All Rights Reserved
  5. Disclaimer: All use is at your own risk.
  6.  
  7.  
  8. Updating your Amiga Include Files
  9. ---------------------------------
  10. Most Amiga C compilers and assemblers should be able to use unmodified
  11. Amiga Include files, but may ship with an older version of the includes.
  12. You should be able to decompress the .h and/or .i archives provided
  13. here, and copy the newer include files over your existing includes
  14. (Note - if you are at all unsure whether your compiler or assembler
  15. can use unmodified Amiga includes, then first make a backup of your
  16. old include directory).  The Amiga includes do not contain any root
  17. level or other compiler-specific include files like stdio.h.
  18. Copying the Amiga includes over your existing includes will only
  19. replace older Amiga-specific include files.  We have used unmodified
  20. Amiga include files with SAS C, Manz Aztec C, DICE, HX68 and Cape.
  21.  
  22.  
  23. Updating your Libs
  24. ------------------
  25. You will also need to update your compiler's linker libs with the
  26. newer Amiga linker libs.  Some compilers can use our libs as-is.
  27. (I believe SAS and Manx are in this category, as well as most
  28. assemblers).  Other compilers may provide a tools which will
  29. allow you to convert our Amiga.lib and other libs to the format
  30. the compiler requires (I believe DICE is in this category).
  31.  
  32.  
  33. Updating Your FD's
  34. ------------------
  35. If you keep the FD files on your system (for use with tools like LVO),
  36. or if your language requires FD files, these may be found in the FD
  37. archive.  Some compilers provide tools which can convert FD files
  38. into pragma or other register interface description files which
  39. can help your code be smaller and faster.  (SAS fd2pragma for example).
  40. The updated LVO tool (from SWToolkit3) can now generate _lib.i style
  41. output for use with assemblers.  LVO, in conjuction with the FD files
  42. (in a directory assigned the name FD:) can also be used to look
  43. up function interface information, or to generate command lines for
  44. Wedge (SWToolkit3).
  45.  
  46.  
  47. Compiling New Code to Work on Older OS's
  48. ----------------------------------------
  49. This is relatively easy.  Just don't use any functions/flags/tags
  50. which are newer than the earliest OS you need to run under.  Consult
  51. the comments in the include files and autodocs for notes on when various
  52. functions/flags/tags/structures were added.  If starting from example
  53. code, you should probably start with examples written for the
  54. earliest OS you need to work under, or search out backwards-compatible
  55. examples which conditionally take advantage of new features.
  56. Check out the 2.0 Addison-Wesley Rom Kernel Manuals, and also the
  57. example code from the 2.0 and 1.3 Rom Kernel Manuals (on Fish Disks).
  58. Then, whenever new functions are available to replace old methods
  59. of allocation or initialization, conditionally use the new methods.
  60. Old methods may not work on all systems and are less upwards-compatible.
  61. Read all of the compatibility documents you can find (see back of
  62. the 2.0 RKM Libraries manual, and see any 3.x Compatibility documents.
  63. And be sure to test your code under all OS's you support.  If you do
  64. anything with graphics or Intuition, be sure to test on an AA machine
  65. with mode promotion on (IControl Prefs).  And if you open on the
  66. Workbench screen, be sure to test with large Workbench fonts, mode
  67. promotion on, AND an odd-sized Workbench screen.
  68.  
  69.  
  70. NOTE: New ASL Tags
  71. The asl.library now supports some new individual tags for
  72. old features.  Many features which could previously only be accessed
  73. via FuncFlag tag bits now have their own tags.  Warning - even
  74. though many of these features existed even in V37 asl.library,
  75. the new individual tags for requesting them ARE NOT INTERPRETED until
  76. V38 asl.library.  If you need to be compatible with V37 asl.library,
  77. see the old tag and bit definitions at the end of asl.h.
  78. A better solution for Workbench license-holders is to distribute
  79. the V38 asl.library with your program (a free ASL amendment is
  80. available for Workbench license holders.  The V38 asl.library also
  81. is the earliest asl.library which contains the screen mode requester.
  82.  
  83.  
  84. NOTE: New Safer Intuition Flag Names
  85. Old code often had problems with Intuition flags being set in the
  86. wrong fields or being used incorrectly.  New consistent flag
  87. names with prefixes were added in V37.  Use of these new names
  88. for old features (such as WFLG_SIZEGADGET and IDCMP_GADGETUP)
  89. makes it difficult to sets flag bits in the wrong places. 
  90. Note that these new flag names for old intuition features
  91. generally have the same bit values as the old names, and may
  92. be used for any version of Intuition which support the feature.
  93. To enforce use of the newer/safer/consistent naming conventions, new
  94. code which uses Intuition should include the following #define before
  95. including any intuition headers, and should use only the new names for
  96. the various Intuition flags.  Use of the following #define will prevent
  97. use of the old flag names which are now in  intuition/iobsolete.h
  98.  
  99. #define INTUI_V36_NAMES_ONLY
  100.  
  101.  
  102.  
  103. Compiling Old Code
  104. ------------------
  105. Old code should compile fine with newer includes except for the
  106. fact that compilers have grown smarter and pickier.  Many old
  107. coding mistakes may be picked up.  In addition, the default settings
  108. for compilers have changed, often to base-relative settings, so
  109. code containing subtasks or handlers will probably require newer
  110. compiler switches to disable base-relative data or special compiler
  111. directives added to the subtask or handler code (consult your
  112. compiler manual).  In addition, by default, many compilers now
  113. require prototypes (ours are in clib/) and this is good, so you
  114. might need to start including prototype files, and perhaps add some
  115. casting to places where compilers didn't complain before.  One other
  116. compiler-dependent thing is how to disable a compiler's CTRL-C handling.
  117. For example, old code might disable old Lattice's  CTRL-C handling but
  118. the same lines might not disable SAS's CTRL-C handling.
  119.  
  120. For SAS or Lattice, these lines should work fine unless you need
  121. to include the SAS root level dos.h header which contains an incorrect
  122. prototype which conflicts with this:
  123.  
  124. #ifdef __SASC
  125. void __regargs __chkabort(void) {}      /* Disable SAS CTRL-C checking. */
  126. #else
  127. #ifdef LATTICE
  128. void chkabort(void) {}                  /* Disable LATTICE CTRL-C checking */
  129. #endif
  130. #endif
  131.  
  132.  
  133.  
  134. What Files Do You Need To Include ?
  135. ===================================
  136.  
  137. A relatively small set of Amiga include files will handle most simple
  138. programming needs.  Check out the set in the skeleton C program below.
  139. Those will pull in the definitions for return codes, memory allocation,
  140. Library structures, screens, windows, and simple graphics, plus your C
  141. compiler's prototypes and definitions for stdio, file io, etc.
  142.  
  143. You will need to add these include files to the skeleton for the following
  144. common activities:
  145.  
  146. devices/(whatever).h    - If using the (whatever).device
  147. dos/dosextens.h        - If using process or packet structures
  148. dos/exall.h        - If using ExAll
  149. dos/rdargs.h        - If using ReadArgs
  150. exec/tasks.h        - If you have subtasks or need to access tasks
  151. exec/interrupts.h    - If you have interrupt code
  152. graphics/gfxmacros.h    - If you need graphics macros
  153. hardware/(xxx).h    - If you need bits/registers of some Amiga hardware
  154. libraries/asl.h        - If using asl.library (and clib/asl_protos.h)
  155. libraries/diskfont.h    - If using diskfonts
  156. libraries/gadtools.h    - If using gadtools (and clib/gadtools.h)
  157. utility/tagitem.h    - If manipulating tags (and clib/utility.h)
  158. workbench/startup.h    - If parsing Workbench startup args
  159. workbench/workbench.h    - If accessing icons or tooltypes (and clib/icon.h)
  160.  
  161.  
  162. If you still have unresolved structure/flag names, you can look
  163. them up in the C Cross Reference in the 2.0 Addison-Wesley Includes
  164. and Autodocs manual, or use C:search as follows to find the file which
  165. defines what you are looking for:
  166.  
  167.     search include:#?/#?.h structname (or flag name)
  168.  
  169.  
  170. Sample Skeleton C Program
  171. =========================
  172. Example of a simple skeleton C program where "xxxx" can be globally
  173. replaced with the program name.
  174.  
  175. ;/* xxxx.c - Execute me to compile me with SAS C 6.x
  176. SC xxxx.c data=near nominc strmer streq nostkchk saveds ign=73
  177. Slink FROM LIB:c.o,xxxx.o TO xxxx LIBRARY LIB:SC.lib,LIB:Amiga.lib ND
  178. quit
  179. */
  180.  
  181. #include <exec/types.h>
  182. #include <exec/memory.h>
  183. #include <dos/dos.h>
  184. #include <intuition/intuition.h>
  185.  
  186. #include <clib/exec_protos.h>
  187. #include <clib/dos_protos.h>
  188. #include <clib/intuition_protos.h>
  189. #include <clib/graphics_protos.h>
  190.  
  191. #include <stdlib.h>
  192. #include <stdio.h>
  193. #include <string.h>
  194.  
  195.  
  196. #ifdef __SASC
  197. void __regargs __chkabort(void) {}      /* Disable SAS CTRL-C checking. */
  198. #else
  199. #ifdef LATTICE
  200. void chkabort(void) {}                  /* Disable LATTICE CTRL-C checking */
  201. #endif
  202. #endif
  203.  
  204.  
  205. #define MINARGS 1
  206.  
  207. UBYTE *vers = "\0$VER: xxxx 40.1";
  208. UBYTE *Copyright = 
  209.   "xxxx v40.1\n(c) Copyright 1993 Commodore-Amiga, Inc.  All Rights Reserved";
  210. UBYTE *usage = "Usage: xxxx";
  211.  
  212. void bye(UBYTE *s, int e);
  213. void cleanup(void);
  214.  
  215. /* library bases here
  216. struct Library *IntuitionBase = NULL;
  217. etc.
  218. */
  219.   
  220. void main(int argc, char **argv)
  221.     {
  222.  
  223.     if(((argc)&&(argc<MINARGS))||((argc>1)&&(argv[argc-1][0]=='?')))
  224.     {
  225.     printf("%s\n%s\n",Copyright,usage);
  226.     bye("",RETURN_OK);
  227.     }
  228.  
  229. /* library opens here
  230.     if(!(IntuitionBase = OpenLibrary("intuition.library",37)))
  231.     {
  232.     bye("Can't open V37+ intuition.library",RETURN_FAIL);
  233.     }
  234. etc.
  235. */
  236.  
  237.     bye("",RETURN_OK);
  238.     }
  239.  
  240.  
  241. void bye(UBYTE *s, int e)
  242.     {
  243.     if(*s) printf("%s\n",s);
  244.     cleanup();
  245.     exit(e);
  246.     }
  247.  
  248. void cleanup(void)
  249.     {
  250. /* library closes here
  251.     if(IntuitionBase)    CloseLibrary(IntuitionBase);
  252. etc.
  253. */
  254.  
  255.     }
  256.  
  257.