home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 2: PC / frozenfish_august_1995.bin / bbs / d09xx / d0959.lha / IntuiMake / IntuiMake.doc < prev    next >
Text File  |  1993-12-10  |  18KB  |  533 lines
  1.                               IntuiMake v1.2
  2.  
  3.                  ⌐ 1993 Bj÷rn E. Trost and Dirk O. Remmelt.
  4.  
  5.  
  6.  
  7. i. Rights and duties of the authors
  8.  
  9.    IntuiMake v1.2 was created and tested with the biggest care possible.
  10.    Nevertheless, bugs in the program itself and bugs in programs created
  11.    with IntuiMake can't be locked out. The authors can't be made liable
  12.    for such bugs.
  13.  
  14.  
  15.  
  16. ii. Rights and duties of the user
  17.  
  18.    IntuiMake is a tool for developers, created with the intention of
  19.    building complex projects, with an easy to use graphics user interface.
  20.    No further knowledge about conventional makes is needed, because
  21.    Intuimake does not deal with script files or things like that.
  22.  
  23.    Intuimake is intended to be copied freely as long as the price of the
  24.    disk is not more than $6, DM 5.- or the equivalent in any other
  25.    currency. If you like to include IntuiMake in a Public Domain series,
  26.    please send a copy of your finished disk.
  27.  
  28.    IntuiMake must not be recompiled or changed in any form. This relates
  29.    especially to copyright messages and versionnumbers.
  30.  
  31.    IntuiMake is no shareware, but it is possible to register. Registered
  32.    users get updates, a printed documentation set with TeX and a good
  33.    support. A register card can be found in the file `Register.txt' in
  34.    this package. Interested users can print it out and send it to me.
  35.  
  36.    Of course you can write to me without being registered. If you want
  37.    reply, please send an international postal coupon.
  38.  
  39.  
  40.  
  41. iii. Contents of this package
  42.  
  43.    This software package should include the following files:
  44.  
  45.    ╖ IntuiMake:               The executable program.
  46.    ╖ IntuiMake.anl:           German documentation.
  47.    ╖ IntuiMake.doc:           This documentation.
  48.    ╖ NewlookMake:             A special version of IntuiMake.
  49.    ╖ Register.txt:            Register card.
  50.    ╖ Registrierkarte.txt:     German register card
  51.    ╖ example/first.c
  52.    ╖ example/first_protos.h
  53.    ╖ example/headerfile.h
  54.    ╖ example/makefile
  55.    ╖ example/main.c
  56.    ╖ example/second.c
  57.    ╖ example/second_protos.h
  58.    ╖ example/test
  59.    ╖ example/obj/first.o
  60.    ╖ example/obj/main.o
  61.    ╖ example/obj/second.o
  62.  
  63.  
  64.  
  65. 1. The purpose of a make
  66.  
  67.    A make is a tool for compiling a program, which consists of several
  68.    modules, in a comfortable way. Especially the compilation of one
  69.    or more modules if a headerfile has changed, should be made automatically.
  70.  
  71.    The version 1.2 of IntuiMake deals only with the Manx Aztec compiler.
  72.  
  73.  
  74.  
  75. 2. Starting, needed files, ...
  76.  
  77.  
  78.    IntuiMake needs OS2.0 and the asl-library in LIBS:. By default, the
  79.    makefile is created as `makefile' in the actual directoy.
  80.  
  81.    IntuiMake should be started from the CLI/Shell with <run IntuiMake>.
  82.    A filename of a makefile can be specified: <run IntuiMake mymakefile>.
  83.  
  84.    After starting, IntuiMake opens a window which is draggable and
  85.    sizeable. The default settings are loaded and IntuiMake is ready.
  86.  
  87.    It is recommended, not to start IntuiMake without a CLI/shell, because
  88.    the messages of the compiler and the linker are not redirected. Always
  89.    use a CLI/Shell and IntuiMake together. Fortunately the Amiga can
  90.    multitask...
  91.  
  92.  
  93.  
  94. 3. The screen after starting
  95.  
  96.    After starting and loading the makefile the main window opens itself.
  97.    The biggest part is covered with the listview gadget. It contains all
  98.    modules which belong to the program which should be created.
  99.  
  100.    Below are the gadgets for starting the compilation, for starting an
  101.    editor and for running and debugging the program.
  102.  
  103.    In the right are string gadgets for defines which are to be set or not,
  104.    name of the files to be created, versionnumber and a switch for
  105.    activating the debug information.
  106.  
  107.    The window can be sized and positioned on the screen. These dimensions
  108.    are saved in the makefile.
  109.  
  110.  
  111.  
  112. 4. The menus
  113.  
  114. 4.1 Project
  115.  
  116. 4.1.1 Save makefile
  117.       Select this for saving the current makefile. The filename is
  118.       `makefile' or the specified name on startup.
  119. 4.1.2 Save makefile as ...
  120.       Sometimes it is useful to deal with more than one makefile. With the
  121.       ASL filerequester a filename for the makefile can be chosen.
  122. 4.1.3 Load makefile ...
  123.       For loading a makefile on runtime, this can be selected. The ASL
  124.       filerequester appears and the makefile can be chosen.
  125. 4.1.4 Delete objectfiles ...
  126.       The purpose of a make is, making as much as possible automatically.
  127.       But there are several things which force a module to be compiled
  128.       what IntuiMake does not recognize. This could be the copying of an
  129.       older module to the actuals. To force IntuiMake compile this
  130.       module, the object file (*.o) should be deleted. This can be done
  131.       with the ASL filerequester and multiselection (holding the shift key
  132.       pressed).
  133. 4.1.5 Edit preferences ...
  134.       In the preferences window many options can be selected:
  135. 4.1.5.1 Comparing
  136.       IntuiMake offers the possibility of comparing two sets of modules,
  137.       e.g. for recognizing differents to an older version. For that,
  138.       the two paths of the modules must be given. The file which is
  139.       created must be specified in the `output' string gadget.
  140. 4.1.5.2 Scanning
  141.       The automatic search for dependancies can be made faster by
  142.       specifying a string (in remarks) after the `#include' commands.
  143.       This string can be specified with `EndString'. If also the
  144.       beginning of the `#include' statements should be recognized,
  145.       `BeginString' must contain the string which signals the
  146.       beginning of the `#include's. If these strings should be used can
  147.       be declared for C and assembler modules.
  148.       The cycle gadgets for the syntax of the `#include' statements
  149.       should only be used, if other compilers or assemblers than the
  150.       Aztec are used.
  151.       In future versions IntuiMake should be completely independent of the
  152.       compiler and should be programmable.
  153. 4.1.5.3 Paths
  154.       With the cycle gadget is for chosing, if an executable program or a
  155.       linker library should be created. If a linker library should be
  156.       created, the tools `Lb' and `Ord', both supported by Manx, must
  157.       be in the actual path.
  158.       In the main window a module can be edited by clicking on `Edit'. For
  159.       that, the desired editor, e.g. `Ed' must be specified in the string
  160.       gadget `Editor'.
  161.       If a precompiled headerfile is used, it must be declared in the
  162.       string gadget `-hi file'. Should the headerfile be used for
  163.       compilation, the compiler option `-hi' must be activated in the
  164.       options window.
  165.       For archiving the modules, headerfiles and the makefile, the archive
  166.       name must be declared in the `Archive' gadget.
  167.       The path in which the modules can be found should be specified in the
  168.       `Sourcecode' gadget. The object files which are created need not to
  169.       be in that path. They can stand anywhere. The path for them can be
  170.       specified in `Objectcode'.
  171. 4.1.6 Edit linkeroptions ...
  172.       Here the options for the Aztec linker are to be declared. They can
  173.       be found in the Aztec manual. `Additional modules' stands for all
  174.       oject files or libraries which are not declared as modules, e.g.
  175.       `-lmf -lc'.
  176. 4.1.7 About ...
  177.       A requester, created with MaxonPAINT, appears.
  178. 4.1.8 Quit
  179.       Used for exiting IntuiMake.
  180.  
  181.  
  182. 4.2 Action
  183.  
  184. 4.2.1 Make ...
  185.       Starts the compiling and linking. A window opens, in which the
  186.       module, which is to be compiled, is shown. With the close gadget
  187.       compiling can be canceled. With the gadget `Edit' the actual module
  188.       can be edited. `Retry' starts the compilation again. `Next' skips
  189.       the module and compiles the next one. `Make' starts again with all
  190.       modules.
  191. 4.2.2 Edit
  192.       Starts the editor specified in the preferences. The editor can be
  193.       started with double clicking the module in the listview gadget, too.
  194. 4.2.3 Run
  195.       Starts the created program.
  196. 4.2.4 Debug
  197.       Starts the debugger `sdb'.
  198.  
  199.       The menuitems listed above can also be activated by the gadgets below
  200.       the listview gadget, which is faster.
  201.  
  202.  
  203.  
  204. 4.3 Modules
  205.       Intuimake handles C modules and assembler modules. Assembler modules
  206.       should have the postfix `.asm'.
  207.  
  208. 4.3.1 Insert modules...
  209.       With the ASL filerequester the modules, which belong to the program,
  210.       can be declared. Multiselection with the shift key is supported.
  211.       New modules can be added at any time.
  212. 4.3.2 Delete module
  213.       The actual module is deleted by selecting this.
  214. 4.3.3 Scan module
  215.       IntuiMake offers the possibility of recognizing dependable
  216.       headerfiles. Doing this, the actual module is scanned for
  217.       `#include"'. All headerfiles are recognized recursively, as long as
  218.       all dependancies are recognized.
  219.       To force scanning be more faster, scanning can be canceled if the
  220.       declared string in the preferences is found. This is especially
  221.       useful at larger modules. The string should be set below the last
  222.       `#include' statement.
  223. 4.3.4 Scan all modules
  224.       All modules are scanned for includes. Canceling is done by clicking
  225.       the close gadget.
  226. 4.3.5 Compare set of modules
  227.       If two or more programmers develop one project, the modules must
  228.       be joined together. IntuiMake offers the possibility of comparing
  229.       two sets for differences. The tool `Diff', which is
  230.       shipped with the compiler, is called. In the preferences the two
  231.       paths and the file in which the changes are written, must be
  232.       declared.
  233. 4.3.6 Archive set of modules
  234.       With the tool `Lha' by Stefan Boberg all modules, headerfiles and the
  235.       makefile are archived. The name of the archive must be specified in
  236.       the preferences.
  237. 4.3.7 Edit options
  238.       For selecting the compiler or assembler options for each module,
  239.       this menuitem must be selected. Five default settings, which can
  240.       be programmed freely and affect alle modules, and one custum
  241.       setting, which is different for each module, can be set.
  242.       For setting the default options for one or more modules, `As default'
  243.       should be selected after setting the options.
  244.  
  245.  
  246.  
  247. 5. Defines
  248.  
  249.      Conventionally, symbols or defines can be transmitted to the compiler
  250.      via the -d option. Up to five selectable defines can be declared in
  251.      the string gadgets in the right half of the main window. The checkbox
  252.      gadget left of the stringgadget selects the defines or not. This is
  253.      useful in statements like these:
  254.  
  255.         #ifdef DEMO
  256.                Save ();
  257.         #else
  258.                puts ("Demoversion!");
  259.         #endif
  260.  
  261.  
  262.  
  263. 6. Creating a project
  264.  
  265.      In this section the configuration of IntuiMake and the working with it
  266.      shall be described. For that, the package includes an example project,
  267.      which consists of three modules which are linked together.
  268.  
  269. 6.1 An example
  270.  
  271.      Here are the modules:
  272.  
  273.  
  274.         /* main.c
  275.         **
  276.         **
  277.         */
  278.  
  279.         #include "first_protos.h"
  280.         #include "second_protos.h"
  281.         /* SCAN_END */
  282.  
  283.         void main (void)
  284.         {
  285.           Test1 ("Test it:", 1);
  286.           Test2 ("Just do it:");
  287.         }
  288.  
  289.  
  290.  
  291.  
  292.         /* headerfile.h
  293.         **
  294.         ** SCAN_END
  295.         */
  296.  
  297.         struct MyStruct
  298.         {
  299.           int  a;
  300.           long b;
  301.         };
  302.  
  303.  
  304.  
  305.  
  306.         /* first.c
  307.         **
  308.         **
  309.         */
  310.  
  311.         #include "headerfile.h"
  312.         /* SCAN_END */
  313.  
  314.         void Test1 (char *message, long var)
  315.         {
  316.           struct MyStruct mystruct = {1, 2L};
  317.  
  318.           printf ("%s %d\n%d\n%d\n", message, mystruct.a, mystruct.b, var);
  319.  
  320.         }
  321.  
  322.  
  323.  
  324.  
  325.         /* second.c
  326.         **
  327.         **
  328.         */
  329.  
  330.         #include "headerfile.h"
  331.         /* SCAN_END */
  332.  
  333.         void Test2 (char *message)
  334.         {
  335.           struct MyStruct mystruct = {3, 4L};
  336.  
  337.           printf ("%s %d\n%d\n", message, mystruct.a, mystruct.b);
  338.         }
  339.  
  340.  
  341.  
  342.  
  343.         /* first_protos.h
  344.         **
  345.         ** SCAN_END
  346.         */
  347.  
  348.         void Test1 (char *message, long var);
  349.  
  350.  
  351.  
  352.  
  353.         /* second_protos.h
  354.         **
  355.         ** SCAN_END
  356.         */
  357.  
  358.         void Test2 (char *message);
  359.  
  360.  
  361.      In `headerfile.h' a structure `MyStruct'áis declared, which is used in
  362.      the modules `first' and `second' and must therefor be included. `main'
  363.      does not need this structure. It only needs the prototyp declarations
  364.      for `Test1' and `Test2'. This means, that `first_protos.h' and
  365.      `second_protos.h' must be included from `main.c'.
  366.  
  367.      With these informations all dependancies are clear. If one of the
  368.      files others depend on, change, all dependable files must be compiled.
  369.      Here is the scheme, but do not worry: This is only done for
  370.      clarity.
  371.  
  372.      (a -----> b means, that b depends on a.}
  373.  
  374.  
  375.             first_protos.h -----> main.c <----- second_protos.h
  376.  
  377.  
  378.  
  379.             first.c <----- headerfile.h -----> second.c
  380.  
  381.  
  382.  
  383.      If the function `Test1' is changed into
  384.  
  385.                void Test1 (char *message1, short var)
  386.  
  387.      the file `first_protos.h' must be changed, too. This also causes
  388.      that `main.c' must be compiled because the calling of `Test1'
  389.      has changed. `Second.c' need not be compiled.
  390.  
  391.      If the structure `MyStruct' is changed in a way like that:
  392.  
  393.                struct MyStruct
  394.                {
  395.                  short a;
  396.                  long b;
  397.                };
  398.  
  399.      `first.c' and `second.c' must be compiled because both modules work
  400.      with it. `main.c' does not need this structure and needs not to be
  401.      compiled.
  402.  
  403.      This should be a short introduction into dependancies. But as I said
  404.      before: Do not worry, this knowledge is not needed because IntuiMake
  405.      has it!
  406.  
  407.  
  408.  
  409.  
  410. 6.2 The settings for the example
  411.  
  412.     For the creation of an executable program out of the sourcecode some
  413.     things must be done first, which are described here:
  414.  
  415.     First, IntuiMake must be started: <Intuimake'> or <run IntuiMake>
  416.  
  417.     After the successfull starting, the modules must be included. For
  418.     that, the menuitem `Modules/Insert modules ...' must be selected.
  419.     The ASL filerequester appears and the modules can be added by
  420.     holding the shift key pressed and selecting the modules `first.c',
  421.     `second.c' and `main.c'. The headerfiles and prototyp declarations
  422.     must not be selected.
  423.  
  424.     The selected files appear in the listview gadget in alphabetical
  425.     order.
  426.  
  427.     Next, the compiler options for each module are to be declared.
  428.     The desired module and the menuitem `Module/Edit options' must be
  429.     selected. A window with all compiler options supported by the Aztec
  430.     compiled appears.
  431.  
  432.     With the cycle gadget one out of five default settings or one custom
  433.     setting can be chosen. The defaults are useful if the same options
  434.     are used for different modules. The options should be set as desired,
  435.     after that, `As default' must be selected. The options are saved and
  436.     used for all other modules which use the same default settings.
  437.  
  438.     If the options are declared, the version string of the program, e.g.
  439.     `1.2' should be set. IntuiMake creates the version string as recommended
  440.     by Commdore.
  441.  
  442.     Below the name of the program to be created should be set.
  443.  
  444.     Next the window for the linker options should be opened with
  445.     `Project/Edit linker options ...'. `Additional modules' should be set
  446.     to `-lc' because the l-library is needed.
  447.  
  448.     At last, the compiling is started with `Action/Make'. A window opens,
  449.     in which the amount of modules, which are already compiled, is
  450.     displayed. If an error occurs, the module can be corrected by clicking
  451.     `Edit'. `Retry' compiles the module again.
  452.  
  453.     After a successfull compilation and linkage, the program can be started
  454.     via `Run'.
  455.  
  456.  
  457. 7. Why must a module be compiled?
  458.  
  459.    Following a list of events which force the compilation of a module:
  460.  
  461.    ╖ An object file does not exist.
  462.    ╖ The module was changed.
  463.    ╖ A headerfile, which the module depends on, was changed.
  464.    ╖ The state of a define has changed, and the define is used in the
  465.      module.
  466.  
  467.  
  468.  
  469. I. Credits
  470.  
  471.    No program without credits: First we would like to thank Commodore
  472.    Business Machines Inc. and Commodore Bⁿromaschinen GmbH for lot of
  473.    uncounted jokes they made. Thank you, Commodore.
  474.  
  475.    Further we would like to thank Manx Software Systems fo delivering a
  476.    non-functioning make and a non-existing environment. Thank you, Manx.
  477.  
  478.    But enough of the cynicisme, a big Thank You to Maxon Computer, Eschborn
  479.    Germany, for an examplary developer support. Thank you, Maxon.
  480.  
  481.  
  482.  
  483. II. I like that ol' time rock and roll ...
  484.  
  485.  
  486.    Great acoustic performances: ╖ Eric Clapton: Unplugged
  487.                                 ╖ Bruce Sptringsteen: (Un)plugged
  488.                                 ╖ Neil Young: Unplugged
  489.                                 ╖ Rod Stewart: Unplugged and seated
  490.  
  491.    Great electric performances: ╖ Emerson, Lake & Palmer: Live at the
  492.                                                           Royal Albert Hall
  493.                                 ╖ Rush: Exit...stage left
  494.                                 ╖ Deep Purple: Made in Japan
  495.                                 ╖ Toto: Absolutely live
  496.  
  497.    Great new albums:            ╖ Deep purple: The battle rages on
  498.                                 ╖ Rush: Counterparts
  499.                                 ╖ Def Leppard: Retro active
  500.                                 ╖ Dio: Strange highways
  501.  
  502.    Great concerts in Europe:    ╖ Deep Purple: The battle rages on,
  503.                                                Oct 1993
  504.                                 ╖ Ronnie James Dio: Strange highways,
  505.                                                     Dec 1993
  506.                                 ╖ Robert Plant: Fate of nations,
  507.                                                 Dec 1993
  508.                                 ╖ Pink Floyd: *************
  509.                                               Aug 1994
  510.  
  511.  
  512.  
  513. III. Epilogue
  514.  
  515.    If you want to contact us, please write to
  516.  
  517.  
  518.                               Bjoern E. Trost
  519.                          Auf dem Baennjerrueck 39
  520.                            67663 Kaiserslautern
  521.                                   Germany
  522.  
  523.                                     or
  524.  
  525.                               Dirk O. Remmelt
  526.                              Lutrinastrasse 11
  527.                            67655 Kaiserslautern
  528.                                   Germany
  529.  
  530.  
  531.  
  532.   Kaiserslautern, in November of 1993
  533.