\documentstyle{article} \begin{document} \title{VisualMaker} \author{David L\"ubbren\\Leopoldstr. 3\\76133 Karlsruhe\\Germany} \maketitle \begin{abstract} {\bf VisualMaker} is a Tool for automatically generating a {\tt DMakefile} for {\bf DiCe}'s Make utility. Features include a fully graphical user interface, automatic scanning of source files for headerfile dependancies and handling of precompiled header dependancies. Supports all {\bf DiCe} compiler options and uses symbol names and variable assignments in the output file, grouping all files with the same options together. Takes into account the environment variable {\tt DCCOPTS}.\\ Version 1.0. Requires AmigaDOS2.0. Binary only. \end{abstract} \newpage \tableofcontents \newpage \section{Legal Stuff} VisualMaker V1.0 \copyright David L\"ubbren. {\bf VisualMaker} is SHAREWARE, and may be distributed in a non- commercial way (you may copy, spread, and use it but don't make money out of it). If you like {\bf VisualMaker} and regularly use it, I would appreciate being sent a {\bf \$10} contribution to the above address. Contributors will receive the complete copyrighted source in C. Suggestions, comments and criticisms are also welcome at the above address. If any problems are encountered, please report them! \centerline{Disclaimer} DAVID L\"UBBREN MAKES NO WARRANTIES EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS SOFTWARE, ITS QUALITY, PERFORMANCE OR FITNESS FOR ANY PARTICULAR PURPOSE. THIS SOFTWARE IS PROVIDED "AS IS." THE ENTIRE RISK AS TO QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH THE USER. IN NO EVENT WILL DAVID LÜBBREN BE LIABLE FOR DIRECT, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT IN THE SOFTWARE. \section{Introduction} {\bf VisualMaker} is a 'MakeFile' generator for the {\bf DiCe} compiler package. The program is fully controlled through an Intuition interface and allows compiler options to be set for individual files with just a couple of mouse clicks. All compiler options are supported. The generated {\tt DMakefile} includes the basic object $\rightarrow$ source, executable $\rightarrow$ object dependancies as well as dependancies for all included headers, precompiled headers and errorfile deletion prior to a new run. The output format is such that all files with the same options and headers are arranged in groups and referenced through symbolic names where possible. {\bf VisualMaker} reads your {\tt DCCOPTS} environment variable and shows them on the GUI. An option is included for setting this variable. Header dependancies are obtained through scanning of the source files recursively, so even deeply nested subheaders are found. Every time a headerfile is edited the dependant sources get recompiled. If the precompile option is selected, precompiled headers will be deleted if any of their dependancies are altered, thus causing {\bf DiCe} to precompile anew. If compiler error output is redirected to a file, this errorfile will be deleted prior to every new compile run. Only headers included in double quotes (e.g. \verb- #include "defs.h"-) will be searched for (angle brackets should be reserved for system headers). Headers included inside of plain C comments (\verb# /*...*/ #) will be ignored, nested comments are not supported. The {\tt DMakefile} itself includes a list of dependancies and commands necessary for creating the executable, the object files, disassembled files, automatic deletion of the Errorfile on startup, and for deletion of objects and preprocessed files. \section{Usage} Invoke {\bf VisualMaker} from the directory where you would like the {\tt DMakefile} to be written to. This is usually the directory containing the brunch of your source files and from where the compiler is started. The first thing {\bf VisualMaker} will do after invocation is to read your {\tt DCCOPTS} environment variable, if found, and activate the corresponding gadgets to reflect your default settings. Choose all the files for your project with the {\bf {\sf GetFile}} Gadget in the upper left corner (underneath the {\bf {\sf Generate}} Button). This will bring up an ASL File\-Re\-quester. You can multiselect files by simultaneously pressing the {\bf Shift} key. Alternatively you can use the {\bf {\sf A}} Button (All) to choose all the files in your current directory in one go. The files will show up in the {\bf {\sf Source List}} ListviewGadget. (All files without a {\tt .c}, {\tt .a} or {\tt .o} extension will be filtered out, as well as object files which have a corresponding source). To remove files from the list, select them and press the {\bf {\sf R}} Button (Remove). Now you can select your compiler options. The options are divided into two classes, the global compiler options, which are located underneath the {\bf {\sf Source List}} Listview gadget, apply to all files in your project (e.g. Resident, Small/Large-Data model), and the local compiler option, above the {\bf {\sf Source List}} ({\bf {\sf proto, --H, Stack, NoProf}}). These may apply to only particular files (e.g. profiling of only the time critical routines) as well as to all files. To turn on local options select the files in question. To select a single file, press the left mousebutton (LMB) over the file name. To select several files, drag the mouse while keeping the LMB pressed. To select (or unselect) files which are momentarily not in the visible region, drag the mouse over the rim of the gadget while keeping the button pressed. Pressing a local option button now will effect the selected files, showing the option behind the file name. For a comprehensive explanation of the individual compiler options see the DiCe documentation ({\tt dcc.doc}). The Program Name defaults to one of the source filenames in the Source List (minus the extension). The name can be easily changed to another source filname by selecting that particular file in the Source List, or of course by typing it into the string gadget. The {\bf {\sf Errorfile}} StringGadget specifies the output of compiler (Error)messages which is by default {\tt STDOUT}. The {\bf {\sf Output Dir}} StringGadget determines where the object files are written to. If not specified they are written into the same directory as the source files. The {\bf {\sf Temporary Dir}} StringGadget specifies the directory for preprocessed files. \pagebreak[4] To generate the {\tt DMakefile} press the {\bf {\sf Generate}} Button. All Files will now be scanned, searching for any included headers in double quotes (e.g. {\tt \#include "defs.h"}) and, if found, these will be scanned as well, searching for subheaders and so on. Note: headers inside of comments will not be searched. After the file has been written into the current directory the program will exit. To leave the program without writing the {\tt DMakefile}, press the Close-Window gadget, or select {\bf {\sf Exit}} in the menu. \section{Gadgets} \begin{description} \item[CloseWindow] terminates the program {\it without} writing the {\tt DMakefile}. \item[Generate] The {\tt DMakefile} will be written, and {\bf VisualMaker} will terminate. \item[GetFile] Pressing the {\bf {\sf GetFile}} Gadget brings up either a file- or directory requester. Some of the Requesters allow multiselection by holdding down the {\bf Shift} key. After selection, files/directories will be listed in the corresponding listview-gadget. \item[Source List (ListviewGadget)] All Sourcefiles chosen with the File\-Re\-quester or {\bf {\sf A}} button are listed. Any {\tt .o} or {\tt .a} files which also have a corresponding {\tt .c} file will {\it not} be listed. When a particular file is selected the local compiler options apply to this file. (De-)Selection is simply done by pressing the nouse button over a particular source name. Keeping the button pressed and dragging, allows multiselection. The name of the executable is automatically set to the last selected file. \item[R (Remove)] Removes a selected File/Directory/Path from a Listview Gadget. \item[A (All)] This is a convenience button to select all files in the current directory, bypassing the filerequester. Only files with a {\tt .c}, {\tt .a} or {\tt .o} extension are selected and shown in the listviewgadget. If a source and object file of the same name exist, only the source file will be shown. e.g. \begin{quote} \begin{tabbing} \tt spalteeinssssss\=arrow\=spaltezwei\kill CURRENT DIR \> \>Source List\\ main.c main.o \> $\rightarrow$ \> main.c\\ main.a main.o \> $\rightarrow$ \> main.a\\ main.o \> $\rightarrow$ \> main.o \end{tabbing} \end{quote} In other words, object files will only be shown if they are {\it extra objects}. \item[Program Name] Name of the executable program. If you select a filename from the Source List the extension will automatically be truncated and the rest placed into this string gadget. If this mechanism annoys you, just simpy type something into this Gadget manualy (a {\tt RETURN} will do) and the name will be {\it frozen}. \item[Errorfile] Compiler error messages can be diverted to a particular file instead of {\tt STDOUT}. Useful if you have a means of proccessing these from your Editor with say an AREXX-script. \item[Output Dir] The Directory where all object files ({\tt .o}) will be written to. If not specified, each objectfile will be written into the same directory its source resides in. \item[Temporary Dir] The Directory where preprocessed files are written to. \end{description} \section{Local Compiler Options} \begin{description} \item[--proto] Sets the {\tt -proto} compiler option, enabling prototype checking. All functions not prototyped will cause an error during compilation. For the amiga library functions, the corresponding \verb-*_protos.h- files in the 'clib' direrctory have to be included. When compiling with registered arguments ({\tt -mr/-mR/-mRR)} prototyping is mandatory. \item[--H] Any header files referenced in the source file with \verb-#include "name.h"- ({\bf Notice}: Header file in Quotes, {\it not} angle brackets) will be precompiled and placed into the temporary directory (Default: {\tt T:}) with the name {\tt name.m}. This can speed up compilation time tremendously. In the {\tt DMakefile} a dependancy will be created, deleting the precompiled file whenever the corresponding headerfile or any subheaders included in it are changed causing the compiler to generate a new precompiled file. To precompile system headers e.g. \verb-- or \verb--, just include them in a header- or subheaderfile, not in the source files or replace the angle brackets with double quotes, but you'll probably have to add an absolute path. \item[Stack/--mr/--mR/--mRR] Handling of function arguments. \begin{description} \item[Stack] allows normal passing of function arguments via the stack. \item[--mr] cause the compiler to create both a stack and registered argument entry point for functions. \item[--mR] cause the compiler to generate a single registered argument entry point for each function. \item[--mRR] as above, but extends registration to indirect function calls. \end{description} The registered argument options switch on prototyping automatically, as this is mandatory. \item[NoProf / --prof1 / --prof2 / --prof3] En-/Disable profiling of either only the source ({\bf {\sf --prof1}}), source and clib functions ({\bf {\sf --prof2}}) or source, clib and amigalib functions ({\bf {\sf --prof3}}). With the latter two options, objects are linked with the corresponding profiling libraries. \end{description} \section{Global Compiler Options} \begin{description} \item[Resident] Sets the {\tt -r} compiler option, or if {\bf {\sf No Reloc Hunk}} is enabled the {\tt -pr} compiler option. This makes the code resident. \item[Dynamic Stack] Sets the {\tt -gs} compiler option, adding code for automatic stack allocation if stack falls below a certain limit. (I have encountered some problems with this option). \item[No Reloc Hunk] Sets either {\tt -pi}, or {\tt -pr} if {\bf {\sf Resident}} is also enabled, causing the compiler {\it not} to generate a relocation hunk. \item[Small Data / Large Data] Sets the {\tt -md / -mD} compiler options to create either a small (PC-relative) data model, or a large (absolute) data model. \item[OS 2.0 / OS 3.0 / OS 1.3] Sets the {\tt -2.0 / -3.0 / -1.3} compiler options, telling the linker with which amiga library to link with. \item[C${\tiny ++}$ Comments] Sets the {\tt -//} comiler option, letting the compiler recognize C${\tiny ++}$ style comments. \item[Verbose] Sets the {\tt -v} compiler option which will show all {\tt dcc} commands in {\tt STDOUT} while executing. \item[68000 / 68020 / 68030] Sets the {\tt -020 / -030} options, specifing the processor for which the executable is written. (Default {\bf {\sf 68000}}) \item[Small Code / Large Code] Sets the {\tt -mc / -mC} compiler options for either small code (Default) or large code model. \item[--ms0 / --ms1 / --ms2] \begin{description} \item[--ms0] only {\tt const} data is put in code-hunk. \item[--ms1] string constants are also placed in code-hunk. \item[--ms2] as above, but all external {\tt const} references use near addressing. \end{description} \item[--unix] Objects are linked with the unix libraries. \item[--chip] Force all hunks into chip memory. \item[NoCoPro / --881 / --882] Tells the compiler to produce floatpoint code for corresponding co-processor. \item[--lm] Objects are linked with the maths library for float\-point output e.g. \verb-printf("%lf", ...)-. By default this is turned on whenever {\bf VisualMaker} encounters an \verb-"%*lf"- in the source code. See also the menu options. \item[--s] Add symbolic debugging information in the executable. \item[--I0] Remove default include paths. \item[--L0] Remove default library paths. \end{description} \section{The Backpanel} As you've probably noticed, you access this second panel of gadgets by pressing the LMB anywhere inside the window outside of gadget activation areas. The top row of gadgets activates more esoteric options of the compiler and I will not go into these (see {\tt dcc.doc}). The listview gadgets underneath allow you to specify additional link libraries, library- and include paths. Their functionality is the same as with the {\bf {\sf Source List}}. \begin{description} \item[Link Library] You may specify additional libraries you want to link your code with. Only files with a {\tt ".lib"} extension are accessible through the library- requester. It is generally not necessary to add a particular model of the standard c-, amiga-, or maths-library here since these are automatically dealt with. (e.g. {\tt muis.lib} - if you're working on a MUI project). \item[Library Paths] Specify additional paths (directories) where the compiler should look for libraries if they are not located in the standard {\tt DLIB:} directory. \item[Include Paths] Specify additional paths where the compiler should look for include files not found in the standard {\tt DINCLUDE:} directory. The specified path will also be searched by {\bf VisualMaker} if it can't find one of your header files either in the current directory or the one the corresponding source file is located in. \end{description} \section{The Menues} \begin{description} \item[DCCOPTS] This will pop up a requester allowing you to save the currently set compiler options in {\bf VisualMaker} to the {\tt DCCOPTS} environment variable. Three options are available: \begin{description} \item[SAVE] Options are saved permanently in {\tt ENVARC:DCCOPTS}. \item[USE] Options are saved in {\tt ENV:DCCOPTS} and will be gone when computer is turned off (provided your {\tt ENV:} directory is in {\tt ram:}). \item[CANCEL] Self-explanatory. \end{description} \item[check \%lf] This option causes {\bf VisualMaker} to search for any output of float-point numbers in the source code and if found automatically set the {\tt "-lm"} option in the DMakefile which causes the compiler to link with math library enabling output of {\tt float} and {\tt double} numbers (if not used float numbers are literally ouput as \verb-""-). The program does not actually look for a \begin{quote} \begin{verbatim} '(s|f|v)printf("%...f")' \end{verbatim} \end{quote} command but rather just the format string \begin{quote} \begin{verbatim} "%[0-9.l+-\*]*(E|e|f|F|g|G)", \end{verbatim} \end{quote} that is it does not know whether the expression is inside a printf- family type of command or just a simple string. The option is on by default but if it causes any problems due to the above mentioned, just turn it off (the {\tt -lm} option increases the executable size). \item[EXIT] Leave program without writing the {\tt DMakefile}. \end{description} \section{Using the DMakefile} {\tt DMake} can be called with several keywords, which determine what it does. These are: \begin{description} \item[{\tt {\bf DMake} all}] \item[{\tt {\bf DMake} $<$executable$>$}] -generates the executable (Program Name), recompiling everything that's necessary. The previous errofile (if specified in {\bf VisualMaker}) is deleted prior to compilation. Note, if a full pathname was specified for the executable in {\bf VisualMaker} it should also be input here. This is case sensitive. \item[{\tt {\bf DMake} $<$file$>$.o}] -generates only the specified object file. Note, if an output directory was given this will have to be included, and is also case sensitive. e.g. {\tt OUTDIR = dtmp: , OBJ = main.o \\ $\Longrightarrow$ DMake dtmp:main.o} and not {\tt DTMP:main.o} \item[{\tt {\bf DMake} $<$file$>$.a}] -generates only the specified disassembled file. The same applies as above. \item[{\tt {\bf DMake} clean}] -deletes all object-, precompiled- and error- files. \item[{\tt {\bf DMake} cleano}] -only deletes all objectfiles. \end{description} \section{Making Protos} If you want a dependancy for the automatic creation of a prototypes file (e.g. {\tt protos.h}) then create an environment variable called {\tt MAKEPROTO}. Place a string with your {\tt makeproto} calling format followed by a blank and then the prototype filename. \begin{description} \item[Example1:] If you use Matt Dillon's {\tt makeproto} and your prototype file is called {\tt protos.h} use the following command: \centerline{\verb+ Setenv MAKEPROTO "makeproto -o protos.h protos.h"+} \item[Example2:] If you use Eric Smith's Public Domain {\tt mkproto} utility (my choice, since it extracts the prototypes directly out of the declared functions) use the following command: \centerline{\verb+ Setenv MAKEPROTO "mkproto >protos.h protos.h"+} \end{description} To make this setting permanent copy {\tt env:MAKEPROTO} into the {\tt envarc:} directory. \section{Timer Problems} DMake uses the time-stamp of the files to determine whether a recompilation is neccessary. If you do not have a clock, or it doesn't always function properly (mine sometimes sets itself back to {\tt Jan-78}) in an unlucky case it could happen that a freshly edited dependent file has an older time stamp than its target file, causing {\tt DMake} not to resolve the dependency (and your bug-fix or added feature not showing up). \begin{quote} e.g. having the following dependancy, {\tt main.o : main.c\\ \ \ dcc main.c -o main.o\\} \end{quote} say the target {\tt main.o} already exists from a previous session, in this session your timer misbehaves (setting itself back to the 70's) and you edited {\tt main.c}, the new file won't be recompiled. The solution is either \begin{enumerate} \item to always check and set the timer before starting a session, \item to manually set the date of {\tt main.c} with {\tt Date} or {\tt touch} to something newer than {\tt main.o}, \item just simply by deleting the target {\tt main.o}. \end{enumerate} \section{Make Primer} {\tt Make} is a utility program included in all serious compiler-packages that automates the recompilation process for large programs made up of several files. When making changes to a particular file only those files which are directly influenced by these changes (i.e. which are dependant ) are recompiled, usually not all of them, which can result in tremendous time savings as well as relieving the programer from the burden of remembering and typing endless lines of compiler commands. {\tt Make} uses the file time-stamp in its considerations. The {\tt Make} program is driven by a Makefile which consists of a list of file dependancies and command lines. Consider the following simple example: \begin{quote} {\tt main.o : main.c\\ \ \ dcc -c main.c -o main.o} \end{quote} Here {\tt main.o} (target file) depends on {\tt main.c} (dependant file). If the dependant file is newer than the target file or the target does not exist, the dependancy is resolved, that is the command below is executed. Several other forms of declaring dependancies are available. Furthermore commands may be AmigaDOS commands such as {\tt Delete} etc. For details of the syntax see the DMake manual. (A feature not documented is the prefixing of commands with a minus sign which will inhibit premature termination of {\tt DMake} if a command returns an error or warning). Anyway, with {\bf VisualMaker} you should not have to worry about this!! Even if you are just compiling a single file, a DMakefile can still be of use. Your particular compiler options are saved and you don't have to worry about deleting the 'errorfile' (if redirected) prior to a new run (remember, the errors and warnings are always appended). An option I particularly recommend is the precompilation of header files. If you have enough memory, all headers, including the system headers (e.g. \verb- -) may be precompiled. Since the compiler will then only have to read them {\it once} from your diskdrive, this saves a lot of time. To do this put all your definitions and (system) include files in one header, say {\tt defs.h}, and reference them with \verb-#include "defs.h"- from every source file which needs them. \end{document}