Greg Banks $Date: 2003/11/01 02:29:37 $ This is version &version; 2000 2001 2002 2003 Greg Banks Permission is granted to copy, distribute and/or modify this document under the terms of the Open Publication License, version 2.0. Maketool is a GUI program for running the GNU make utility, or &gmake;, to build software. GNU make is a powerful utility for organising the process of compiling and linking software, and is widely used in Open Source and commercial software.

This is maketool's main window. The various parts of the main window are: menubar Each menu contains commands which allow you to drive maketool. The menubar can be detached from maketool by dragging the handle at the left. Each menu can be detached from maketool by selecting the dashed line at it's top. See also , , , , and . toolbar Each tool is a shortcut to a menu item, arranged for your convenience. The toolbar can be detached from maketool by dragging the handle at the left. See also , , tool, tool, , tool, tool, . log window This window shows the output of &gmake;. As shown in the example, errors and warnings are highlighted; double-clicking on an error or warning will start an editor showing you the line in the source file which caused the error or warning. Errors and warnings are distinguished by both colors and icons. You can change the colors in the . The presentation of text in the log window is controlled by various options in the . status bar Messages from maketool itself (rather than &gmake;) are displayed here. progress indicator When &gmake; is running, this area displays an animation of a brick wall building itself, to show you that something is happening.

Click this button to apply all the changes you have made to this dialog window and close the window. See also: ,

Click this button to apply all the changes you have made to this dialog window, without closing the dialog window. See also: ,

Click this button to discard all the changes you have made to this dialog window and close the dialog. See also: ,

Open Log... Shows the which allows you to choose a filename of &gmake; output to be opened and displayed in maketool. This file can be a file saved by the Save Log... menu item, or a file generated from the command line using a command like: # If you use sh, ksh, bash gmake some-target 2>&1 | tee make.log # ...or... gmake some-target > make.log 2>&1 # If you use csh, tcsh gmake some-target |& tee make.log # ...or... gmake some-target >& make.log Save Log... Shows the which allows you to choose a filename to which the text in the will be saved. The file will contain the raw text from all &gmake; runs, exactly as &gmake; emitted it. The file can later be loaded into maketool again using the Open Log... menu item, or viewed in a text editor. Change Directory... Shows the which allows you to choose a directory. Maketool will make that directory it's current directory. Maketool will then scan any Makefile present in the directory and show the targets defined by the Makefile in the . Maketool will also detect what if any make system (see ) is in use in that directory, and show menu items accordingly. Finally, maketool will add the old directory to the Previous Directories menu. Previous Directories Lists the last directories in which maketool has been used. Select a directory, and maketool will change to that directory as if you had used the Change Directory... menu item. The previous directories are saved along with maketool's preferences, and will be there next time you start maketool. Edit Makefile... Starts up an editor session editing the Makefile in the current directory. If the current directory uses a system like autoconf or Imake to generate the Makefile from another source file, that other source file will be edited instead. The filenames checked by this menu item are (in order): The filename, if any, specified by in the Preferences. The filenames searched by the current make program. For &gmake;, these are: &GNUmakefile; &makefile; &Makefile; If no Makefile is present, or it's filename is &Makefile;, the following filenames are also checked (in order): &Makefileam; (for automake) &Makefilein; (for autoconf) &Imakefile; (for Imake) Print... Shows the to allow you to print the contents of the to a printer. Exit Quits maketool. Note that if you haven't saved the contents of the , maketool will NOT ask you if you want to save.

Edit Error Starts an editor session editing the source file and line mentioned in the line currently selected in the . Edit Next Error Searches forwards in the for the next error or warning message, starting at the currently selected line, and starts an editor session editing the source file and line mentioned in that line. If the option is set, Edit Next Error will ignore warnings and only find errors. Edit Prev Error Like Edit Next Error but searches backwards. Edit Next File Error Like Edit Next Error but first skips to the next source file. This is useful when an error early in a source file confuses the compiler and generates many spurious errors. Copy Copies the text of the currently selected line in the to the clipboard, from where it can be pasted into a text editor. Find... Shows the which allows you to search the contents of the . This menu item is available when there is text in the log window. Find Again... Repeats the last search (from the ). This menu item is available once a search has been performed. Preferences... Shows the which allows you to edit maketool's various options and parameters.

Again Runs &gmake; with the same target you used last time you ran &gmake; (from the , the tool, or the tool). The target is shown in brackets. This menu item is available when &gmake; has been run at least once. Stop Stops a running &gmake;. This menu item is only available while a &gmake; is running. Pause/Resume Pause pauses a running &gmake;, and Resume resumes running a paused &gmake;. This menu item is only available while a &gmake; is running and paused respectively. Dryrun Only While this checkbox is on, &gmake; does not perform any building, and instead only shows the commands it would use for building. This is useful for debugging &Makefile;s. This option uses the -n flag to &gmake;. Makefile Updates the &Makefile; from whatever files are used to create it. This command only appears if the current directory uses a make system (see ) to generate the &Makefile;. Maketool can also perform this update automatically every time a target is built; see the checkbox. make system commands The section of the menu between the first and second separators shows commands related to the make system used in the current directory. See for a description of each command. This section is updated when the current directory is changed using the menu item. standard targets The section of the menu between the second and third separators shows all the targets defined by the Makefile in the current directory, which are standard targets described by the GNU Makefile Standards. Those targets, and their standard meanings are described in . Selecting a target causes that target to be built using &gmake; and the output from &gmake; to be displayed in the . This section is updated when the current directory is changed using the menu item. non-standard targets The section of the menu after the third separator shows all the targets defined by the Makefile in the current directory, except those which are standard targets, and except certain targets which maketool considers "internal" to the Makefile. Selecting a target causes that target to be built using &gmake; and the output from &gmake; to be displayed in the . This section is updated when the current directory is changed using the menu item.

Clear Log Clears all text in the log window. This menu item is available when there is text in the log window. See . Collapse All Collapses all the text in the log window so that only the top level entries (i.e. &gmake; runs and loaded log files) are visible. This menu item is available when there is text in the log window. Toolbar Controls whether the is visible. Hiding the toolbar reduces the amount of screen space maketool needs. Statusbar Controls whether the is visible. Hiding the statusbar reduces the amount of screen space maketool needs. Errors Controls whether lines of text which are classified as errors by the filtering engine, are visible in the log window. Warnings Controls whether lines of text which are classified as warnings by the filtering engine, are visible in the log window. Information Controls whether lines of text which are classified as information (i.e. all lines which are not classified as errors or warnings, and do not have summaries like compile lines) by the filtering engine, are visible in the log window. Summary Controls whether lines of text which are not classified as warnings or error but have short summaries (e.g. "Compiling fred.c") generated by the filtering engine, are visible in the log window. Indent Directories If this checkbox is on, the text of recursive multiple-directory &gmake; runs in the log window is indented according to depth in the directory structure. Each directory is accompanied by a collapse/expand button so that entire sub-trees can be conveniently hidden with the click of a button. See the menu item.

About Maketool... Shows the , which contains copyright, licence, and version information about maketool. About GNU make... Shows the , which shows copyright, licence, and version information about the &gmake; program. Note that if a different make program is selected in the entry of the Preferences, this menu item will reflect the name of that make program, e.g. About BSD 4.4 pmake. Help on... Allows you to interactively pick a component of the maketool user interface and see the help text for that component. When the menu item is selected, the cursor changes to a question mark (?); move the cursor over any component of the maketool user interface and click. The help text for that component will be displayed in the help browser. Table of Contents... Shows the maketool help Table of Contents in the help browser. Web Page... Shows the maketool web page in the help browser.

Click this tool to run &gmake; with the same target you used last time you ran &gmake; (from the , the tool, or the tool). The tooltip shows you which target this will be. This tool becomes available once you have started at least one &gmake; run. See also: tool, tool, tool

Click this tool to stop the current &gmake; run. This tool becomes available only during a &gmake; run. See also: tool, tool, tool

Click this tool to pause the current &gmake; run. Click it again to resume the run. This is useful for stopping the build temporarily e.g. while you do something else in a shell window. This tool becomes available only during a &gmake; run. See also: tool, tool

Click this tool to run &gmake; with the target all. Makefiles which adhere to GNU Makefile standards will compile and link all programs and libraries (but not necessarily any documentation). This tool becomes available if the &Makefile; in the current directory defines an all target. Like all build tools and menu items, it becomes unavailable while &gmake; is running. See also: tool.

Click this tool to run &gmake; with the target clean. Makefiles which adhere to GNU Makefile standards will delete all files which are normally created by building, such as programs, libraries, and object files, but not files which record the configuration. Use this to force a complete rebuild after changing the configuration, or after setting variables like CFLAGS or CC in the . This tool becomes available if the &Makefile; in the current directory defines a clean target. Like all build tools and menu items, it becomes unavailable while &gmake; is running. See also: tool

Click this tool to delete all text in the log window. This toolbar button becomes available when the log window contains text. See the menu item.

Click this tool to edit the next error or warning after the currently selected line in the log window. If the Edit Next ignores warnings toggle in the Preferences window is set, this button will skip over warnings and only find errors. This tool becomes available when the log window contains text. See also:

Click this tool to edit the next error or warning after the currently selected line in the log window. Unlike the tool, this tool first skips all errors and warnings in the same file (compilation unit) as the selected line. This is useful when an error early in the file confuses the compiler. If the option is set, this tool will skip over warnings and only find errors. This tool becomes available when the log window contains text. See also: tool.

Click this tool to pop up the which you can use to print the text in the log window. This tool becomes available when the log window contains text.

This window is shown when you select the menu item, and allows you to choose a file to be loaded into the log window.

This window is shown when you select the menu item, and allows you to choose a filename to which the contents of the log window will be saved.

This window is shown when you select the menu item, and allows you to choose a directory. Maketool will make that directory its working directory and update the to reflect the targets in that directory's Makefile. See the menu.

This window is shown when you select the menu item, and allows you to send the contents of the log window to a printer. Print to printer If this checkbox is selected, the print output will be sent to the printer currently selected in the adjacent combo box. Print to file If this checkbox is selected, the print output will be sent to the filename currently selected in the adjacent combo box. Click the Browse button to choose a new filename. &OK; Click &OK; to generate the print output and send it to the currently selected destination. Page Setup... Click Page Setup... to show the of the Preferences. &Cancel; Click &Cancel; to close the Print window without generating any print output.

This window is shown when you select the menu item, and allows you to search for words or regular expressions in the text in the log window. Search for: Enter the string or regular expression you want to search for, in this text field. You can use the PageUp key on the keyboard to recall the last string you searched for; use the PageUp and PageDown keys to move through the history of all previous search strings. Press the Return key on the keyboard to perform the search. Literal Select this checkbox if you want the string in the Search for text field to be interpreted as a plain string, i.e. regular expression metacharacters are not significant. Regular Expression Select this checkbox if you want the string in the Search for text field to be interpreted as a regular expression, i.e. regular expression metacharacters are significant. See the system manual page regex(7) for details of regular expression syntax. Search Forwards Select this checkbox if you want maketool to search for the search string starting at the currently selected line in the log window and moving forwards (towards the end of the log window). Search Backwards Select this checkbox if you want maketool to search for the search string starting at the currently selected line in the log window and moving backwards (towards the start of the log window). Wrap Select this checkbox if you want maketool to continue searching from the start of the log window when it reaches the end without finding a matching line (or, if the Search Backwards checkbox is on, continue from the end when it reaches the start without finding a matching line). Find Click Find to perform the search. If maketool can find a line in the log window matching the parameters in the Find window, it will select that line, otherwise it will beep and show the message "Pattern not found" in the statusbar. Once you have performed a search, you can repeat the search without opening the Find window by using the menu item. Close Click Close to close the Find window.

This window allows you to set preferences which control various aspects of maketool's operation. All the preferences are saved in the file $HOME/.maketoolrc when you press the &OK; button and at certain other times. The Preferences window is divided into several panes:

This pane is part of the which is shown when you select the menu item. Make runs commands This area controls the way in which &gmake; runs the commands specified in the Makefile to build targets. in series: commands are run one at a time, one after the other. in parallel, with a limit on the number of processes (commands) run at the same time. Equivalent to using the -j option to &gmake;. in parallel, with a limit on the machine load (number of commands which can execute at any time). Equivalent to using the -l option to &gmake;. Automatically edit first error If this checkbox is on, maketool will automatically open a text editor on the filename and line number mentioned in the first error message in a &gmake; run, as soon as the error message is added to the log window. Edit Next ignores warnings If this checkbox is on, maketool will skip warning messages and only select error messages when you use the , , or menu items, or the or tools. Continue despite failures If this checkbox is on, &gmake; will continue building targets after a target fails to be built. The normal behaviour of &gmake; is to stop when the first target fails. Equivalent to using the -k option to &gmake;. Build Makefile from Imakefile or Makefile.in If this checkbox is on, maketool will attempt to rebuild the Makefile in the working directory from a &Makefileam;, &Makefilein; or &Imakefile; file, every time a target is built. See for more information. Scroll to end on output If this checkbox is on, maketool will scroll to the end of the log window every time new text is added to the end of the log window. On starting each build: This combobox allows you to specify an action which maketool will perform just before starting each &gmake; run. Do nothing: maketool does not do anything special before each build. Clear log: maketool clears all text from the log window before each build (as if you had used the menu item). Collapse all log items: maketool collapses all the indented text in the log window (as if you had used the menu item). On finishing each build: This combobox allows you to specify an action which maketool will perform just after finishing each &gmake; run. Do nothing: maketool does not do anything special after each build. Beep: maketool emits a beep after each build. Run command: maketool runs the command in the adjacent text field after each build, using all the maketool and environment variable overrides. Maketool does not show the output of this command, wait for its completion, or take any notice of its exit code. Typically, you would use this command to notify yourself that a build has finished. Show dialog: maketool shows a dialog (shown below) after each build, which describes the target built and how many errors and warnings were found. This is useful when your window manager provides multiple virtual desktops; you can start a build, change to another virtual desktop, and be notified when the build finishes. You may need to configure your window manager to show dialogs on the current virtual desktop instead of with the parent application. Makefile: This combobox can be used to force &gmake; to use a different filename than the default for the Makefile (equivalent to the -f option). You can select one of the standard filenames in the menu, or type in any filename, or click the Browse button to choose a filename. If you enter an absolute pathname (i.e. one that begins with the root directory, such as /usr/foo/bar/Makefile), that one Makefile will be used regardless of maketool's working directory. This is probably not what you want, as most Makefiles are not written to be used like that. Normally you do not need to use the Makefile combobox, as &gmake; will figure out which Makefile to use by itself. Use the combobox only when you need to force &gmake; to use a non-standard filename for the Makefile. For example, when testing new Makefile features a name of Makefile.test would be useful.

This pane is part of the which is shown when you select the menu item. It allows you to set up &gmake; variable overrides which are used every time you build a target. The main scrolling list shows the current set of variable overrides, with their name, value, and type. The other items on this pane allow you to add, change and remove from this set. Clicking the &OK; button accepts the variable overrides so that they will apply to the next &gmake; run Variable overrides are currently not saved in the preferences file, so you have to enter them every time you start maketool. . Maketool supports overriding &gmake; variables in two different ways, shown in the scrolling list as the `Type' of the variable override. Make Variable overrides of this type are passed the &gmake; on the commandline as a sequence of arguments of the form NAME='VALUE'. The %v escape sequence in maketool commands is replaced with this sequence of options (see for other sequences). Note that the behaviour of the Make type variable overrides with recursive builds depends on which make program is selected in the field in the Preferences; &gmake; will pass down the overrides to child makes and subdirectories, many other make programs do not. Environ Variable overrides of this type are passed to &gmake; in the process environment, as if you had used the shell export (sh, ksh, bash) or setenv (csh, tcsh) commands. Note that the behaviour of variables set in the environment depends on which make program is selected in the field in the Preferences, and how the Makefile is written. The value you specify may well be ignored. Environ type variables are useful for passing variables to autoconf &configure; scripts, particularly the CC and CFLAGS variables. To add a new variable override: enter a name in the Name text field, enter a value in the Value text field, choose a type from the Type combobox, and click Set to add the new variable override to the scrolling list. click &OK; to accept the set of variable overrides in the scrolling list. To change an existing variable override: select a variable override in the scrolling list, change the value in the Value text field or the type in the Type combobox. click Set to change the variable override. click &OK; to accept the set of variable overrides in the scrolling list. To remove a variable override: select a variable override in the scrolling list, click Unset to remove the variable override. click &OK; to accept the set of variable overrides in the scrolling list. The controls on this pane are described in detail below. Name This text field shows the name of the currently selected variable override and allows you to enter names of new variable overrides. Names must obey the same rules as &gmake; variable names (see the &gmake; documentation). In addition to the normal TAB key for moving between fields in a window, you can use the equals (=) key to advance to the Value text field. Value This text field shows the value of the currently selected variable override and allows you to enter values of new variable overrides. Values can be any string and may include whitespace There is currently no way you can enter TAB or newline characters in Value text field. and shell metacharacters (although see for pitfalls with metacharacters). Maketool will quote the string if necessary before passing it to a shell. Type This combobox shows the type of the currently selected variable override and allows you to choose types of new variable overrides. Set Click Set to add the name, value and type combination currently in the Name, Value and Type fields into the scrolling list. Note that you need to click the &OK; or &Apply; buttons before the variable override will be used in the next &gmake; run. Unset Click Unset to remove the variable override corresponding to the name currently in the Name text field from the scrolling list. Note that you need to click the &OK; or &Apply; button before the variable override will be removed from the next &gmake; run.

This pane is part of the which is shown when you select the menu item. It allows you to control the way in which maketool runs programs to do various tasks. Make Program: This combobox allows you to choose which make program will be used to build targets. Maketool knows about several make programs including GNU &gmake;, BSD 4.4 pmake, Solaris make and IRIX smake. For each make program, maketool knows the commandline options and other features of the make program necessary to implement maketool features; many of the used to construct commands depend on the value of this combobox. This combobox appeared in maketool version 0.8; before that maketool could only be used with &gmake;. Make a target: The string in this text field is expanded (see ) and run when you start building a target, e.g. all, from the menu or the or tools. The expanded command is appended to the log window as a new top-level indented item; the command's output is filtered for errors and warnings and appended to the log window. List make targets: The string in this text field is expanded (see ) and run when maketool starts and every time maketool changes working directory (i.e. you use the menu item or the menu). The command's output is filtered to extract the set of targets defined by the &Makefile;, in a way which depends on the make program selected in the Make Program: combobox. List make version: The string in this text field is expanded (see ) and run the first time you open the . The command's output is displayed in the About Make window. Edit source files: The string in this text field is expanded (see ) and run every time you edit a source file (using the , , , or menu items, the or tools, or double-clicking on an error or warning in the log window. Maketool discards the command's output and does not wait for the command to finish or check the command's exit code. Build makefile: If the checkbox in the Preferences is on, the string in this text field is expanded (see ) and run just before you start building a target, e.g. all, from the menu or the or tools. The expanded command is appended to the log window as a new top-level indented item; the command's output is filtered for errors and warnings and appended to the log window. Help browser: This text field specifies the command run when maketool's help text or web page is viewed. The program must be capable of displaying HTML text and resolving file: and http: URLs. The only percent escape (see ) expanded is %u. Maketool discards the command's output and does not wait for the command to finish or check the command's exit code.

This pane is part of the which is shown when you select the menu item. It allows you to control the colours used to show errors, warnings, and summarised lines in the log window. The colours are organised by the error severity: information, warning, error, and summary. For each of these there are a pair of colours, background and foreground. Each colour has two controls: A text field which shows the hexadecimal value of the colour. You can type hexadecimal colours directly into this field. If the text field is empty, the default foreground or background of the GTK theme will be used. A Choose... button which when clicked pops up a standard GTK colour selection dialog. Pressing OK in that dialog writes the hexadecimal value of the currently selected colour into the text field. The Colours pane also contains a Sample area which shows you how the currently selected areas will appear in the log window, and these buttons: Reset to Old Click this button to reset the colours to the colours which were in force when the Preferences were last saved. Reset to Defaults Click this button to reset the colours to the compiled-in default colours.

This pane is part of the which is shown when you select the menu item. It is used to configure the page geometry in printed output generated by the . Name: This combobox is used to select one of several international standard paper sizes, or Custom which allows any paper size to be used. Name: This combobox is used to select landscape or portrait orientation. Name: The text box shows the paper width in millimetres, or for Custom paper, allows you to enter a custom paper width. Name: The text box shows the paper height in millimetres, or for Custom paper, allows you to enter a custom paper height. Left: This text field allows you to specify the left margin used for printed output, in millimetres. Name: This text field allows you to specify the right margin used for printed output, in millimetres. Name: This text field allows you to specify the top margin used for printed output, in millimetres. Name: This text field allows you to specify the bottom margin used for printed output, in millimetres.

This window allows you to choose among the various configuration options provided by the &configure; script in the current directory. This window can be opened automatically when the &Makefile; is being updated (if the checkbox is on), or manually by selecting Makefile or Run configure... from the . See for more information. When the window is opened, the options you chose the last time are the default values. An exception is the Do not create output files option, which for obvious reasons is not saved in config.status. This information is read from the config.status file, so it will be used even if you have never used maketool in this directory before. The window has two modes, Basic (the default) and Advanced. The Advanced... button toggles between these two modes.

In Basic mode, the window has the following panes: Directory and file names Contains options related to directories and filenames used by the software package. In Basic mode the only option is Install architecture-independent files in PREFIX, which specifies the directory under which all the software project's files will be installed (e.g. /usr/local). Features and packages Contains options which control user-selectable features of the &configure; script. The exact contents depend on the particular script, and this may pane may not even be present if &configure; is particularly simple. Preview Shows the command line of the &configure; script that corresponds to the options you have chosen. Note that the tooltip on each option shows you the name of the commandline option passed to &configure;.

In Advanced mode, more options become available in all the panes, and two new panes appear: Configuration Contains options related to the behaviour of the &configure; script itself. Host Type Contains options related to cross-compilation. This may pane may not be present if &configure; is particularly simple.

This window shows information about Maketool's version, who owns the copyright, what kinds of warranty you don't have. The Options... button shows the . The Licence... button shows the .

This window shows a listing of all the error filters, makefile systems, and make programs for which support is compiled into the maketool executable.

This window shows the text of the GNU General Public License (or GPL) which is the licence under whose terms Maketool is distributed. For more information on the GPL, please read the GPL FAQ.

This window shows information about GNU make, extracted from the gmake --version command. Note that if a different make program is selected in the entry of the Preferences, this window will show information about that make program instead.

Percent escapes are used when constructing various shell commands which are run by maketool at various times. The command strings are scanned for the escape sequences described below, which are replaced with their expanded text as described below. The various context in which escapes are expanded are: build target The make program is being run to build a target. This happens when a menu item from the is selected or the tool or tool is clicked. list targets The make program is being run to generate the list of available targets in the current directory. This happens automatically when maketool starts or when the current directory is changed using the menu item or the menu item. list version The make program is being run to emit text describing itself, e.g. copyright and version messages. This happens the first time the dialog is opened, and subsequently after the make program is changed in the . edit source A source file is being edited. This happens when an error or warning line in the is double-clicked, the , , , , or menu items are selected, or the tool or the tool are clicked. build makefile The Makefile in the current directory is out of date and the make program is being run to rebuild it. This happens automatically before any target is built if the option is enabled. finished build A build has just finished and the command specified in the item is being run to inform the user. help The help browser is started to view either a local HTML help file or the maketool web page. Note that the table below, "!help" means every context except this one. The available percent escapes are: Escape Context Meaning %D !help maketool's data directory, e.g. /usr/local/share/maketool. %M !help the make program currently selected in the , e.g. gmake %S !help the name of the makefile system automatically detected when maketool is started or the current directory is changed, e.g. automake. %V !help the flags which cause make to print its version to stdout or stderr and exit, e.g. --version. %f edit source the source file name %k !help the flag which causes make to keep on building targets when targets fail, e.g. -k. %l edit source the source line number %m !help if a makefile is defined in the , expands to the make flags necessary to use that makefile, e.g. -f /my/makefile. %n !help flags which cause make to print the commands it would run instead of running them, e.g. -n. %p !help to the flags which implement the parallelism policy controlled by the options, e.g. -j8 %q !help the flags which cause make to dump its internal database to stdout or stderr, e.g. -n -p. Useful only for listing available targets. %t build target target to be built %t list targets the string _no_such_target_ %t finished build target which has just been built %t build makefile filename of the makefile to be built %u help A URL pointing to either a local help HTML file or the maketool web page. %v !help set of make arguments of the form VAR=VALUE for all the variables of type Make in the , e.g. CC=cc. Values have whitespace and shell metacharacters protected with quoting, but see for why shell metacharacters should be avoided. %{x:+y} !help if the simple expansion %x has a non-empty value, expands to the expansion of y, otherwise expands to an empty string. For example, %{l:+-line %l} expands to -line 23 if %l is 23, and expands to the empty string if %l is not defined. Note that while y may contain other simple % escapes the %{x:+y} compound escape cannot be nested.

Metacharacters are "magical" characters which are interpreted in special ways when encountered by a program in it's input. Many different UNIX programs implement metacharacters, and the concept is one the most useful and powerful features of a UNIX system. However, like any powerful tool, unless you know what you're doing you can have some very unpleasant experiences with metacharacters. So unless you know exactly what you're doing, it's wise to avoid using metacharacters in filenames and other data used in maketool. Here be dragons! Usually, metacharacters are the odd punctuation characters around the edge of your keyboard, such as $ * or &. If you stick to using letters, numbers, and the / (slash) - (dash) . (dot) and _ (underscore) characters, you should be fine. If you're still reading this, you either know what you're doing, or you want to know. To discourage you further, here are some of the reasons why metacharacters can cause unwanted consenquences and make debugging painful. Many different UNIX programs (e.g. the shell, &gmake;, sed, m4, awk and the C compiler) interpret metacharacters. Sometimes it's not easy to tell which programs are going to be involved in processing data, especially if you use someone else's complex shell script. All programs have a quoting convention which enables you to quote metacharacters, usually by proceeding the metacharacter with a \ (backslash) character. However, the shell has three quoting conventions, which can interact. Scripts for one program can call other programs (e.g. a shell script calls sed), or build other scripts and then call them. To work properly in the presence of metacharacters, the calling script needs to be aware of the other program's quoting convention; many scripts don't do this. The sets of metacharacters implemented by the various programs overlap, but only partially. For example, ${HOME} has the same meaning in the shell and &gmake; but $(HOME) does not. A similar situation exists with whitespace (space, tab and newline) characters, which are interpreted specially in the shell and &gmake;. If you're still reading this, there is some hope. Sometimes you can achieve what you want with intelligent use of backslash quoting; the trick is knowing how many backquotes you need. Sometimes a combination of backslash and double-quote or single-quote quoting works. Unfortunately the consenquences of too much or too little quoting can be as bad as the problems you were trying to avoid in the first place. Really, the best course is to simply avoid using metacharacters and whitespace when naming files or directories. If you're still not convinced, here's a quick summary of metacharacter-related failure modes when using the autoconf system. First, a quick summary of how autoconf works. The developer uses the autoconf program, which runs m4 to process the file configure.in into a shell script named &configure;, which is then distributed with the application source. The builder runs the &configure; script, which amongst many other things uses awk and sed to process input data. As it's final step, &configure; creates two new shell scripts named config.cache and config.status and runs config.status. The next time &configure; is run, it runs config.cache as it's first step. The config.status script uses sed to create various other files from input templates, usually &Makefile; from &Makefilein; and config.h from config.h.in. Then the builder uses &gmake;, which uses the information in &Makefile; to construct and run shell commands to compile and link the source code. Compilation usually uses information in config.h. At each and every one of these steps, stray metacharacters or whitespace can cause damage ranging from the build process failing with an error, to more dangerous and subtle problems like new files being installed into incorrect directories or over precious system files. Here's a summary of how each character can cause failures in the autoconf chain (for clarity, starting at the step where you run the &configure; script). Metacharacter(s) Failure modes (space) , , (tab) , , ( ) (parentheses) * (asterisk) ? (question mark) [ ] (square brackets) $ (dollar sign) , ; (semicolon) " (double quote) , ' (single quote) , , , \ (backslash) , # (hash mark) ! (exclamation mark) & (ampersand) | (vertical bar) ` (backquote) , < > (less, greater) % (percent sign) , config.site The &configure; script finishes correctly but undesired whitespace expansion causes confusing error messages when &configure; tries to load the site configuration file config.site using a path relative to the directory specified with --prefix. shell The &configure; script works but &gmake; will probably fail due to unexpected expansion by the shell of metacharacters or whitespace in commands given to the shell by &gmake;. This may be solved by adding quoting. gmake runtime The &configure; script works but &gmake; will probably fail due to unexpected expansion by &gmake; of metacharacters or whitespace in commands given to the shell by &gmake;. This may be solved by adding quoting. gmake parsetime The &configure; script works but &gmake; will probably fail due to parse errors in &Makefile; caused by expansion by &gmake; of variables whose values contain metacharacters or whitespace. This may be solved by adding quoting. The error is typically: Makefile:10: *** missing separator. Stop. C strings The &configure; script works but the C compiler will generate syntax errors if metacharacters are used in a string literal in config.h or other C code. balance The &configure; script will fail with shell syntax error if the quotes are unbalanced, i.e. do not occur in pairs. lost The &configure; script works but the metacharacter is lost from values in created files such as &Makefile;. This may be solved by adding quoting. interactive The autoconf system works fine but the metacharacter needs to be quoted when used in an interactive shell session, for example if you use ls to look in a directory whose name contains the metacharacter. If you're still not frightened of metacharacters, go buy a good book on the UNIX shell and read it. Alternatively, the Advanced Bash-Scripting Guide is available online. You will learn a powerful and useful tool.

The name make system is used in this documentation to refer to one of the various systems used to construct a &Makefile; from another source file. These systems are intend to make the creation and maintenance of Makefiles simpler. The important thing to understand about make systems is that the source of a software project which uses one of these systems is delivered without a Makefile. This means that some extra command(s) need to be performed before &gmake; can be run the first time. For people unused to building free software, this represents extra complexity right at the time when they are least equipped to handle it. Maketool tries to soften this impact by: automatically detecting which (if any) make system is used by the software project; providing (in the ) a command to update the Makefile, and various other commands related to the make system; automatically updating the Makefile every time a target is built (if the checkbox is on). Maketool knows about all the popular make systems used with free software today:

This is the most powerful and high-end make system available today. To use automake, you only need to provide the briefest sketch of a &Makefile;, in a file called &Makefileam;, and automake does the rest. Automake requires use of the system for discovering and recording configuration information. See the GNU automake documentation for more information. When maketool detects that the current directory is using automake, the following commands appear in the . Makefile Performs all the actions necessary to update the &Makefile; from whatever files it depends on. This is usually all you ever need to do: it performs all the other commands listed below but in the correct order and only if they are necessary. The output appears in the . Run automake Runs the automake -a command to generate &Makefilein; from &Makefileam;. This is useful when you are working on &Makefileam;. The output appears in the . Run autoconf Runs the autoconf command to generate &configure; from configure.in. This is useful when you are working on configure.in. The output appears in the . Remove config.cache Removes the config.cache file, which is used to cache information discovered by the &configure; script. This is sometimes necessary when you are working on configure.in. The output appears in the . Run configure... Shows the , which allows you to run the &configure; script. This script accepts your configuration choices, discovers various information about the operating system, and finally generates &Makefile; (and usually some other files, such as config.h). The output appears in the . Run config.status Runs the config.status script, which is produced by the &configure; script and generates &Makefile; (and usually some other files, such as config.h). This is useful when you are working on &Makefileam; or config.h.in, because it is faster than running the &configure; script itself. The output appears in the .

Autoconf is a system for discovering configuration information about the operating system, and encoding that information in various files. It is used to avoid portability issues and to provide a standard interface for selecting configurable options. Typically, autoconf will be used to generate the &Makefile; from a file called &Makefilein;, and config.h from a file called config.h.in. However, autoconf is considerably more flexible than this and can be used in other ways. See the GNU autoconf documentation for more information. When maketool detects that the current directory is using automake, the following commands appear in the . Makefile Performs all the actions necessary to update the &Makefile; from whatever files it depends on. This is usually all you ever need to do: it performs all the other commands listed below but in the correct order and only if they are necessary. The output appears in the . Run autoconf Runs the autoconf command to generate &configure; from configure.in. This is useful when you are working on configure.in. The output appears in the . This command only appears if the current directory contains a configure.in file (sometimes software is distributed without this file, although that is not a good practice). Remove config.cache Removes the config.cache file, which is used to cache information discovered by the &configure; script. This is sometimes necessary when you are working on configure.in. The output appears in the . Run configure... Shows the , which allows you to run the &configure; script. This script accepts your configuration choices, discovers various information about the operating system, and finally generates &Makefile; (and usually some other files, such as config.h). The output appears in the . Run config.status Runs the config.status script, which is produced by the &configure; script and generates &Makefile; (and usually some other files, such as config.h). This is useful when you are working on &Makefileam; or config.h.in, because it is faster than running the &configure; script itself. The output appears in the .

Imake is an old-fashioned make system used for building the X Window System and some third-party XWindows and Motif programs. Most uses of imake are being replaced by autoconf, which does the same job but more flexibly. For example, the &configure; script in autoconf has a --help option which shows the user what options are available; there is no equivalent in imake. If your project uses imake, please consider learning . See the imake documentation for more information. When maketool detects that the current directory is using automake, the following commands appear in the . Makefile Performs all the actions necessary to update the &Makefile; from whatever files it depends on. This is usually all you ever need to do: it performs all the other commands listed below but in the correct order and only if they are necessary. The output appears in the . Run xmkmf Runs the xmkmf command to generate &Makefile; from &Imakefile;. The output appears in the .

This section describes the standard Makefile targets which are known by Maketool. This information is derived from the GNU Makefile Standards document, which goes into more detail. Quick Tip: usually the only targets you need to know are all, install, and clean (and use them in that order). all Compile any programs and libraries. check Perform self-tests; to be used between using all and install. clean Delete all files which are normally created by all. e.g. object files, programs, and libraries. Usually used to save disk space or prepare for a complete rebuild. dist Create a source tarball for distribution, e.g. maketool-0.6.2-src.tar.gz. distclean Like all but also removes any files created since the source distribution was unpacked. Usually used to prepare for rebuilding with a new configuration. dvi Used when dealing with Texinfo documentation. Free software is gradually transitioning from Texinfo to DocBook SGML. info Used when dealing with Texinfo documentation. Free software is gradually transitioning from Texinfo to DocBook SGML. install Compile any programs and libraries and copy them into their installation directories (e.g. /usr/local/bin). Some poorly-written Makefiles require you to use all first. installcheck Perform self-tests; to be used after using install. installdirs Create the installation diretories (e.g. /usr/local/bin) if they don't exist. Usually happens as a side effect of install anyway. install-strip Like install but also strip programs of debugging symbols after installation. maintainer-clean Like distclean but cleans even more files. After a maintainer-clean, you can still build the software but may require all sorts of development tools that you might not have installed, such as gperf, automake etc. mostlyclean Slightly weaker version of clean. reallyclean Older name for maintainer-clean. TAGS Update the TAGS file used by the emacs editor. tags Same as TAGS. uninstall Delete the installed copies from installation directories (e.g. /usr/local/bin). Note that the family of "clean" targets form a strict sequence, with each target deleting progressively more files: mostlyclean, clean, distclean, maintainer-clean (aka reallyclean),