The file configure.base consists of a series of m4 macro calls ("commands"). As already mentioned in Basic Concepts, itchconfig translates configure.base to an intermediary Perl script, "configure.pl", which in turn creates the final shell script, "configure". This whole mechanism requires that you pay attention to a few coding style rules in configure.base; the most important rules and some other introductory topics are discussed here.
itchconfig uses m4 in a similar way autoconf does, at least from a configure.base writer's point of view. So, if you are already familiar with autoconf, you can just skip this section.
m4 is a very flexible, powerful macro processor, but this flexibility can cause several problems. Each macro may have several parameters, separated by commas and optional whitespace. (The specific parameters of itchconfig's macros are mentioned in the description of each single macro.) A parameter can contain pretty much any sequence of characters, so m4 sometimes cannot know exactly where a parameter starts and ends (e.g. if a parameter contains a comma) and which characters are intended to be part of the parameter or just whitespace (e.g. if a parameter shall consist of a single space character). To avoid such problems, m4 offers a method to quote the contents of each single parameter; itchconfig uses brackets ("[...]") as m4 quoting characters. As a weird example, if you want to call a macro foo with a comma as the first parameter and a space character as the second parameter, you can't simple write foo(,, ) because m4 would interpret this as three empty parameters, separated by the two given commas; instead you should write foo([,], [ ]). You should also use such quoting if a parameter needs several lines, e.g. some shell script code for an IC_EMIT_SH command.
The documentation of itchconfig's macros sometimes mentions that a parameter is a list, e.g. a list of file names. With m4, the list items are simply separated by single space characters like this: IC_BINARY_CREATE([foo bar baz]). When using a list, you should always quote it in brackets as mentioned above to avoid problems.
The file configure.base should contain at most one command per line. You can add arbitrary comments in lines starting with a "#" character.
With itchconfig, the m4 processor converts each command in a configure.base file to a Perl sub-routine call. If you try to use an unknown command, you'll get an error message like this from the Perl interpreter: "Undefined subroutine &main::command called at ./configure.pl line ..."
Each macro parameter is put into Perl's single-quote characters ('...') in order to ensure a verbatim transfer and to make it easy to digest for the Perl interpreter. One consequence of this is that a parameter itself cannot contain (unescaped) single-quote characters because the Perl interpreter would interpret them as the beginning or end of a parameter. So, if you need a single-quote character in a command parameter (e.g. with IC_EMIT_SH), you must escape it by preceding it with a backslash character ("\") like this: foo([This parameter contains a \' character]).
With itchconfig, you can transfer shell script identifiers from configure.base to the configure script in several ways - directly (e.g. with IC_EMIT_SH) or indirectly (e.g. with IC_SUBSTITUTE, behavior 1). This could cause problems if you accidentally chose an identifier which is also used by the algorithms itchconfig puts into the configure script; in this case, identifiers might be overwritten unpredictably. To avoid such name-space clashes, all your own shell script identifiers should begin with "ICV_", even if not explicitly required by the documentation of a macro; it is guaranteed that itchconfig won't ever use such identifiers itself. (The requirement will be dropped in future versions of itchconfig because the problem will be solved differently, but for now...)
You must not use the shell-builtin command "exit" directly in shell script code because such a premature termination is unexpected for itchconfig's script algorithms and could leave some tasks unfinished, resulting in buggy script behavior. The only acceptable way is an error exit with IC_MESSAGE_ERROR when a fatal error condition occurs.
When you want to use the shell-builtin command "cd", you must do this in a subshell, using the parentheses operator "(...)".
A minimal configure.base file just needs the following two commands:
IC_BEGIN(helloworld, 0.0.0)
IC_END
This tells itchconfig the name ("helloworld") and the current version number ("0.0.0") of the software package. Of course, the configuration script resulting from such a small configure.base wouldn't do much. You should at least add an IC_ENSURE_LAUNCHDIR command and read the description of further (optional) parameters for IC_BEGIN.
If your package contains C source code files from which a binary shall be built (the most important thing with software packages;-), you'll need commands for handling binaries.
If you want to provide users an automated installation with a simple "make install", you'll need installation-related commands.
You might also allow users to enable or disable features of your package. Or perform certain tests, compilations and other actions conditionally. An important concept of itchconfig is that you can substitute identifiers with certain values using IC_SUBSTITUTE. You can also add arbitrary shell script code to the configure script with IC_EMIT_SH, arbitrary C code to the auto-generated config.h file with IC_EMIT_CONFIG_H, and arbitrary targets to the auto-generated Makefile; this makes high flexibility possible.
For more information about all existing commands, you'll have to read the other parts of this documentation. :-) This little overview was just intended as a quick pointer to the most important basic commands. If you'd like to see some "real-life" configure.base files, have a look at itchconfig's own one or that of the web browser retawq.
The documentation of each single macro provides several pieces of information:
When the documentation says that a macro, parameter or functionality you need isn't available since the initial release (itchconfig version 0.0.1), you should add the command IC_META_REQUIRE_VERSION to configure.base.
With itchconfig, certain notions are mostly used as follows: