compiler/include/SDI/doc/README

   1 Short:        SDI headers - A set of C macro/defines to make amiga development easier.
   2 Kurz:         SDI Headers - Ein Bündel von C Makros/Defines um Amiga Entwicklungen einfacher zu machen
   3 Author:       Jens.Langner@light-speed.de (Jens Langner), soft@dstoecker.de (Dirk Stöcker)
   4 Uploader:     Jens.Langner@light-speed.de (Jens Langner)
   5 Version:      1.6 (14.07.2005)
   6 Type:         dev/c
   7 Replaces:     dev/c/SDI_headers.lha
   8 Architecture: ppc-morphos >= 1.4.2; m68k-amigaos >= 2.1.0; ppc-amigaos >= 4.0.0
   9
  10 ABOUT
  11 -----
  12 One may ask, what are these "SDI headers" all about? So let me try to
  13 explain the idea behind those additional headerfiles first:
  14
  15 The so-called "SDI headers" are a set of freely available and freely usable
  16 C-language header files which provide different sets of macros and defines
  17 to make the live of developers much more comfortable when it comes to
  18 dealing with hooks, compiler specific specialities or if one have to keep C
  19 sources compatible over different AmigaOS-like platforms.
  20
  21 In fact, by using the SDI headers a developer might keep his sources simple
  22 and compatible to AmigaOS3, AmigaOS4 and also MorphOS much more easier, than
  23 with having to clutter them with tones of #ifdef statements just because
  24 these platforms use different approaches for the same path.
  25
  26 WHY?
  27 ----
  28 Now you may ask why? The answer is quite easy. Because if you have followed
  29 recent development pathes of AmigaOS3 and its successors AmigaOS4 and
  30 MorphOS, you might have noticed that many parts of the original AmigaOS
  31 API/SDK have been changed. On one hand the API changed because OS4 and
  32 MorphOS are now PPC based, but also because of the senseless "fight" between
  33 those Amiga-based platforms, it is much harder these days for a developer
  34 willing to support all of these platforms at once.
  35 Here is where the SDI headers can clearly help. They release much of the pain
  36 when it comes to deal with Hooks, compiler differences and platform
  37 specialities.
  38
  39 DIFFERENT PURPOSES
  40 ------------------
  41 Currently the "SDI headers" consist of 4 different header files which were
  42 developed because of different purposes:
  43
  44 SDI_compiler.h - This header file carries compiler independent defines and
  45                  macros to allow developers to keep sources compatible to
  46                  different compilers and make sources in all more transparent
  47                  to compilers.
  48
  49 SDI_hook.h     - Dealing with Amiga-hooks was always a bit tricky and hard,
  50                  but in using this header file Hook can be defined in a very
  51                  easy and Amiga-platform independent fashion.
  52
  53 SDI_lib.h      - Since AmigaOS4 a new library system has been introduced
  54                  which comes with a different fashion of dealing with
  55                  shared libraries. This header file allows to keep sources
  56                  compatible to the old scheme by using different types
  57                  of macros making it transparent for AmigaOS3 and MorphOS
  58                  as well.
  59
  60 SDI_stdarg.h   - Unfortunatly variable argument list functions has always
  61                  been a bit tricky and especially since we are on the PPC
  62                  now, developers have to be more careful in how to use
  63                  variable argument list functions. However, this header
  64                  file allows to use a simple set of macros to generate a
  65                  AmigaOS3/AmigaOS4 and MorphOS compatible variable
  66                  argument list function.
  67
  68 SDI_interrupt.h- Dealing with Amiga-interrupts was always a bit tricky and
  69                  hard, but in using this header file interrupts and handler
  70                  can be defined in a very easy and Amiga-platform
  71                  independent fashion.
  72
  73 SDI_misc.h     - This file contains miscellaneous function definitions which
  74                  may be required during development like the PutChProc() for
  75                  RawDoFmt().
  76
  77
  78 So you see. The SDI headers are a global players and if you use the whole
  79 set of these headers your sources can be much easier maintainable than
  80 they are already. Just have a look at the included examples!
  81
  82 USAGE
  83 -----
  84 There is nothing really special about these headers and their usage. All
  85 header files in the "includes" subdirectory of this distributions should be
  86 perfectly commented and can be directly included in any sources.
  87 However, for a better understanding we have worked out some examples which
  88 should illustrate how the SDI headers have to be used and how they are able
  89 to simplify parts of a source code, especially if this source has to be
  90 compatible to many different AmigaOS like platforms.
  91
  92 ARE THEY SERIOUSLY USED YET?
  93 ----------------------------
  94 Of course these headers are not only "theoretical stuff". In fact they are
  95 currently used in the following well-known Amiga-based projects:
  96
  97 YAM (Yet Another Mailer)    - http://www.sf.net/projects/yamos
  98 NList MUI classes           - http://www.sf.net/projects/nlist-classes
  99 MUI (Magic User Interface)  - http://www.sasg.com/
 100 Freeciv (Amiga port)
 101 XAD library
 102
 103 .. and many unknown ones :)
 104
 105 So if you are interested in looking into "real" working source code and not
 106 only into the supplied example code, please feel free to have a look at
 107 the source code of the above projects (if it is freely available of course).
 108
 109 COPYRIGHT
 110 ---------
 111 The header files and sources of the SDI headers and its examples are fully
 112 public domain. They can be reproduced and altered in any way. All we
 113 (the authors) request is that if you find a bug or better way to deal
 114 with something please send us a comment or hint about it so that we can
 115 integrate this stuff in future versions.
 116 Please share the public domain idea to make development for all us small
 117 Amiga developer group easier and so painful in future.
 118
 119 AUTHORS
 120 -------
 121 The main/original authors of the SDI headers are:
 122
 123 Jens Langner <Jens.Langner@light-speed.de>
 124 Dirk Stöcker <soft@dstoecker.de>