Root Makefile.am in Simple KDE App

[Alexander Dymo]

On Monday 07 June 2004 08:48, Steven T. Hatton wrote:
> If anybody cares to annotate the file reproduce below, it would probably be
> valuable for future reference. I've added my questions as comments.  I'll
> do what I can to answer these myself.  The Autotools documentation seems a
> bit inconsistent between different tools, and different versions can have
> important differences which change the meaning of things.  It gets rather
> confusing.
>
> #<project-root>/Makefile.am created by the C++ Simple KDE Application
> template
>
> # What is the purpose of this file?  Where is the documentation for this
> kind # of file?
>
> # Where is the value of TOPSUBDIRS assigned.  When is this expression
> # evaluated? What does SUBDIRS mean, and what purpose does it serve? What
> # value will it have?
> SUBDIRS = $(TOPSUBDIRS)
SUBDIRS is a list of directories to run recursive make in.
$(TOPSUBDIRS) is a variable evaluated by ./configure and represents a list of
directories for make. 
First ./configure saves a list of subdirectories in top source directory - 
$top_srcdir and saves a list of subdirs in $top_srcdir/subdirs file.
Then it looks for $top_srcdir/inst-apps file to check whether a 
particular subdir from $top_srcdir/subdirs should be compiled and installed.
Basically all valid directories listed in $top_srcdir/inst-apps are compiled
and installed (by "compiled" and "installed" i mean that make and make install
will be run).
The list of exceptions should be set in $DO_NOT_COMPILE variable.
You can set it in configure.in.in (for KDE projects) and in configure.in (for
other automake projects).
More information: info:/automake/Top level
You can also list subdirectories by hand in SUBDIRS variable like
SUBDIRS=foo1 foo2 foo3

> # Where is top_srcdir defined? What will its value be? How shoud the
> # expression be read?
$top_srcdir is a usual shell variable evaluated by configure (note that
configure is a simple shell script and configure.in(in) are shell scripts with
m4 macro calls).
$top_srcdir usually evaluates as a directory where ./configure exists
and it is a top source directory.
Additional check to determine if the directory is source directory is done if
you specify AC_CONFIG_SRCDIR macro in configure.in(in).

> $(top_srcdir)/configure.in: configure.in.in $(top_srcdir)/subdirs
> 	cd $(top_srcdir) && $(MAKE) -f admin/Makefile.common configure.in ;
This rule applies for KDE projects which generate configure.in which is
needed by autoconf from your template - configure.in.in and
common KDE template - admin/configure.in.min.

> # What happens here?
> $(top_srcdir)/subdirs:
> 	cd $(top_srcdir) && $(MAKE) -f admin/Makefile.common subdirs
Don't know for sure.

> # What are acinclude.m4 and /admin/acinclude.m4.in ?
> # What happens in this step of processing?
> $(top_srcdir)/acinclude.m4: $(top_srcdir)/admin/acinclude.m4.in
acinclude.* files contain macro definitions which will be expanded to
shell code by autoconf when it creates ./configure script.
admin/acinclude.m4.in contains macroses common for all KDE programs.
Common macroses from admin and your own (if specified in
$top_srcdir/Makefile.am) are collected together into $top_srcdir/acinclude.m4.
When aclocal runs it collects all system macroses and local ones from
$top_srcdir/acinclude.m4 to aclocal.m4.
More information: info:/autoconf/Making configure Scripts

> #  What happens here?  What does `@cd' mean?
> $(top_srcdir)/admin/libtool.m4.in
> 	@cd $(top_srcdir) && cat admin/acinclude.m4.in admin/libtool.m4.in > \
> acinclude.m4
The collection of m4.in files into one acinclude.m4 as I described above.
In simple KDE template there are no "own" m4.in files and only default 
KDE macroses and libtool related ones go into acinclude.m4.
For explanation of @ see below.

> #What is assigned to MAINTAINERCLEANFILES, and how is it used?
> MAINTAINERCLEANFILES = subdirs configure.in acinclude.m4 configure.files
Look at info:/automake/maintainer-mode

> #What is package-messages?  A command? A label? A variable? What is
> `merge'? #What happens when this is evaluated?
> package-messages:
> 	cd $(top_srcdir) && $(MAKE) -f admin/Makefile.common package-messages
> 	$(MAKE) -C po merge
It's a make rule.
The rule looks like:
target: dependencies
	commands
Commands can be any shell commands. If a command is prepended by a @
the command itself is not displayed.
Example makefile:
all:
        @echo "boo"
Results of make:
boo
Example makefile:
all:
        echo "boo"
Results of make:
echo "boo"
boo

Make started without arguments takes first target in makefile and executes all
commands first for dependent targets and then commands for this rule.
More information: info:/make/Introduction

So in that line package-messages is a target and everything else is a shell
command which is considered as an action to "build" the target.
 	$(MAKE) -C po merge
is an instruction to run $(MAKE) in directory po and build a target merge
defined in po/Makefile.
More information: info:/make/Options Summary

> # These are additional files beyond what is processed as source or part of
> the # build system.
> EXTRA_DIST = admin $LICENSEFILE$ configure.in.in
> # What is this step?  What is am_edit? `-padmin'? top_distdir?
> dist-hook:
> 	cd $(top_distdir) && perl admin/am_edit -padmin
> 	cd $(top_distdir) && $(MAKE) -f admin/Makefile.common subdirs
admin/am_edit expands the specialised KDE tags in Makefile.in like 
METASOURCES, KDE_ICON, kde_module etc.
You may consider am_edit as a program which recognizes
KDE-based extentions to Makefile.am syntax which are not supported by
automake.

-- 
Alexander Dymo
ICST Department, National University of Shipbuilding, Mykolayiv, Ukraine