home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / e / autobuild12.lha / AutoBuild / AutoBuild.doc next >
Encoding:
Text File  |  1995-01-12  |  9.2 KB  |  203 lines
  1.                      **********************************
  2.                      *          Autobuild v1.2        *
  3.                      * © 1994-1995 Jan Hendrik Schulz *
  4.                      **********************************
  5.  
  6.                                Indroduction
  7.                                ~~~~~~~~~~~~
  8.    What is autobuild? Autobuild is an automatic build tool for AmigE. It
  9. can do the same think like the build tool that came with AmigaE v3 if it is
  10. used to build programms which are splitted over several modules, but it
  11. does it automaticly. That meens, you need no .build-file to define the
  12. dependencies etc.
  13.  
  14.                                  History
  15.                                  ~~~~~~~
  16. v1.0   - First public release
  17.  
  18. v1.1   - Sources without PROC and EXPORT causing no error anymore.
  19.        - v1.0 doesn't noticed a failing EC or Mac2E sometimes and doesn't
  20.          stop. I hope, this bug is fixed now.
  21.       (- No important changes in this doc-file. You don't need to read
  22.          this docs, if you allready had read the v1.0 docs.)
  23.  
  24. v1.2   - All Mac2E features are removed, because the new AmigeE v3.1 makes
  25.          Mac2E obsolet.
  26.  
  27.  
  28.                     Why using autobuild and not build?
  29.                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  30.    If you are writing a big program and splitt the source into several
  31. modules, you have to change the .build-file everytime when you introduce
  32. a new module, or if a source after some changes needs other modules.
  33.    With autobuild, if you have changed the MODULE information in the source,
  34. autobuild sees automaticly the new dependence and acts accordingly.
  35.    And last but not least, unlike build, autobuild sees circular dependen-
  36. cies between the files. And if you call it with FORCE, every file is still
  37. builded only once! (Maybe the new E v3.1 build does this too?!)
  38.  
  39.  
  40.                               Requirements
  41.                               ~~~~~~~~~~~~
  42.    To use autobuild you need at least Kickstart 2.04 and AmigaE v3.1
  43. If you still use AmigaE v2.1 then use autobuild v1.1 with Mac2E.
  44.  
  45.  
  46.                           How to use autobuild?
  47.                           ~~~~~~~~~~~~~~~~~~~~~
  48.    Autobuild must be called from the shell and it has the following syntax:
  49.  
  50.      TARGET,FORCE=F/S,PRIVATONLY=PO/S,QUIET=Q/S,ECOPTS=EO/K,ECPATH=EP/K
  51.  
  52. TARGET      is the name of the file that should be build. (Without the .m
  53.             if it is a module!)
  54.  
  55. FORCE       tells autobuild to build all files, even if they are allready
  56.             uptodate. (Even with FORCE, every file is build only once!)
  57.  
  58. PRIVATONLY  Normaly autobuild compares the filedate of EVERY used module
  59.             with the filedate of the target to find out, if the target is
  60.             up to date (newer). If you use PRIVATONLY, only the private
  61.             modules (those which names begin with a *) are testet and
  62.             not those in EMODULES:
  63.  
  64. QUIET       Only error-messages (and the output of EC) are printed.
  65.  
  66. ECOPTS      here you can give additional arguments for the EC-call. You
  67.             should write doublequotes around them! Autobuild calls EC like
  68.             this: EC <file> <ecopts>
  69.             Example: autobuild target ECOPTS "QUIET"
  70.  
  71. ECPATH      You can tell autobuild where to find EC and than autobuild
  72.             copies EC to RAM:EC (if needed) and uses RAM:EC instead of EC.
  73.             Example: autobuild target ECPATH "Work:AmigaE/Bin/EC"
  74.  
  75.  
  76.                           The .autobuild file
  77.                           ~~~~~~~~~~~~~~~~~~~
  78.    To make the autobuild call easier, autobuild looks for a file called
  79. ".autobuild" in the currend directory and if it exists, the first line of
  80. this file is passed through ReadArgs() with the template above. So normaly
  81. you can execute autobuild without any arguments. If you use arguments and
  82. additionaly there is an .autobuild-file, both are mixed like this:
  83.  
  84. TARGET, ECOPTS and ECPATH:
  85.    If you give them with the commandline, the corresponding .autobuild
  86.    setting is ignored.
  87.    
  88. FORCE, PRIVATEONLY and QUIET:
  89.    The commandline and the .autobuild-settings are Eor()ed.
  90.  
  91.  
  92.                         How does autobuild work?
  93.                         ~~~~~~~~~~~~~~~~~~~~~~~~
  94.    To see, how autobuild works, I think it's the best way to show you how
  95. the most important PROC of autobuild - build() - works. If you call
  96. autobuild e.g. with 'autobuild abc' then main() calls, after some initial
  97. work, build() with 'abc' as target. And build() works like this:
  98.  
  99.                         *-----------------------*
  100.                         |   PROC build(target)  |
  101.                         *-----------+-----------*
  102.                                     |
  103.                      +--------------+--------------+
  104.                      | Look into 'target.e' to see |
  105.                      | which emodules are used by  |
  106.                      | this source.                |
  107.                      +--------------+--------------+
  108.                                     |
  109.                      +--------------+--------------+
  110.                      | Call build() for every used |
  111.                      | privat emodule to make them |
  112.                      | up to date if necessary     |
  113.                      +--------------+--------------+
  114.                                     |
  115.                      ?--------------+--------------?
  116.                      |      Exists 'target'        |
  117.              +---NO--+     (or 'target.m') ?       |
  118.              |       ?--------------+--------------?
  119.              |                      | YES
  120.              |       ?--------------+--------------?
  121.              |       |  Is 'target.e' newer than   |
  122.              +--YES--+ 'target' (or 'target.m') ?  |
  123.              |       ?--------------+--------------?
  124.              |                      | NO
  125.              |       ?--------------+--------------?
  126.              |       | Is at least one of the used |
  127.              +--YES--+ emodules newer than 'target'|
  128.               \      |      (or 'target.m') ?      |
  129.                \     ?--------------+--------------?
  130.                 \                   | NO
  131.    +-------------+-------------+    |
  132.    | Call EC to build an up to |    |
  133.    | date 'target'-file        |    |
  134.    | (or 'target.m'-file )     |    |
  135.    +-------------+-------------+    |
  136.                  |                  |
  137.                  +----------------+ |
  138.                                    \|
  139.                                 *---+---*
  140.                                 |  END  |
  141.                                 *-------*
  142.  
  143.    The above shoud only give an idea what the PROC build() does. The real
  144. PROC build() works a little bit different! It has some lists in memory to
  145. build every file only once, and to look for the filedate of a file only
  146. once for example, but the result is the same.
  147.  
  148.  
  149.                           Some important infos!
  150.                           ~~~~~~~~~~~~~~~~~~~~~
  151. -  Autobuild reads the source only until it finds the first PROC or EXPORT
  152. keyword to make things faster. Is there no PROC or EXPORT, the whole file
  153. is read.
  154.  
  155. -  To make autobuild not to complicate, the keywords MODULE, PROC and
  156. EXPORT must be on the beginning of the line! (No leading spaces or tabs.)
  157. If they are not at the beginning of the line, autobuild doesn't see them!
  158. On the other hand, if you use the keyword in other situations (e.g.
  159. MODULE after an OPT), make shure that it is NOT at the beginning of the
  160. line to make it invisible for autobuild!
  161.  
  162.  
  163.                           Copyright and Author
  164.                           ~~~~~~~~~~~~~~~~~~~~
  165.          Autobuild is (c) copyright 1994-1995 Jan Hendrik Schulz
  166.  
  167.    Redistributing autobuild is allowed, as long as all files are included
  168. and unchanged, and as long as no profit (direct or indirect) is made by
  169. distributing autobuild!
  170.  
  171.    Autobuild is giftware, if you use it, send me something usefull (money,
  172. an Amiga 4000 or at least a postcard or an e-mail).
  173.                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  174.            My address:   Jan Hendrik Schulz
  175.                          Reinhard-Raffalt-Str. 41
  176.                          94036 Passau
  177.                          Germany
  178.  
  179.              Internet:   schulzj@fmi.uni-passau.de
  180.  
  181.  
  182.                              Disclaimer
  183.                              ~~~~~~~~~~
  184.     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
  185.  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  186.  HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
  187.  OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
  188.  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  189.  PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  190.  PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE
  191.  COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  192.  
  193.     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  194.  WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE
  195.  PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
  196.  GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
  197.  USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
  198.  OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
  199.  THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
  200.  PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
  201.  POSSIBILITY OF SUCH DAMAGES.
  202.  
  203.