The KMake utility

KMake is a utility program to build KCML libraries. It uses an XML based file to describe the libraries, the source file components for each library and the library dependencies. It then executes the kc compiler to assemble each library from its source files building only those that are necessary.

KMake uses the file times of source files to determine whether a library needs rebuilding allowing a single source file to be changed, kmake executed and only the minimum rebuilding done.

Using kconf.xml

KMake can run using a simple bespoke build file, but is best run using kconf.xml as part of a system. If a service called XYZ is defined in kconf.xml, then the libraries may be built with

kmake -b XYZ

A number of elements and environment variables need to be defined in kconf.xml:

kcmltype

The service must indicate the type of libraries to be built, by adding the following XML element to that service.

<kcmltype>6</kcmltype>

Valid values for kcmltype are:

Environment variables

The service should also specify these environment variables

The XML build file

The build file lists all the libraries and programs (KCML7 only) to be compiled. Each library and program has a list of its components (specified by the src tag) and dependencies (specified by the uselibrary and reflibrary tags). The include tag can be used to insert subsidiary XML fragments at any point. The if tag allows for a measure of conditional compilation.

Compiling a KCML7 program is a two pass process. In the first pass the build file is read and a tree is built of the target libraries and program. For each target kmake examines the uselibrary tags which declare the dependencies on other libraries and the tree is ordered such that these must be built before the target. This process determines the eventual build order. Clearly there cannot be circular dependencies on things like records, fields or constants.

In the second pass KCML generates the code for the targets in the correct order and when doing so it needs to check that the right number of arguments and the right types are used on DEFSUB calls. To do this it uses the reflibrary tags for a target which list the libraries that contain functions this target might call.

A simple XML containing all the key elements is presented here:

<?xml version="1.0" encoding="UTF-8"?>
<build>
    <flag name="KCML6Decoration"/>
    <flag name="SearchVars"/>
    <flag name="SearchModuleVars"/>
    <flag name="CodeAnywhere"/>
    <library name="Boot">
        <src file="PROGRAMS/GB/MAING.src"/>
    </library>
    <library name="Constants">
        <src file="PROGRAMS/GB/CONST.src"/>
        <src file="PROGRAMS/CG/CONST.src"/>
        <src file="PROGRAMS/GB/CNW32.src"/>
    </library>
    <library name="DataStructure">
        <src file="GENPROGS/GB/IRECS.src" altfile="PROGRAMS/GB/IRECS.src"/>
    </library>
    <library name="CoreFunctions">
        <uselibrary name="Constants"/>
        <uselibrary name="DataStructure"/>
        <uselibrary name="Boot"/>
        <src file="PROGRAMS/GB/libGN.src"/>
        <src file="PROGRAMS/GB/libKI.src"/>
        <src file="PROGRAMS/GB/libKD.src"/>
        <src file="PROGRAMS/GB/libR8.src"/>
        <src file="PROGRAMS/GB/libSF.src"/>
        <src file="PROGRAMS/GB/libPR.src"/>
    </library>
    <library name="Administrator">
        <uselibrary name="Constants"/>
        <uselibrary name="CoreFunctions"/>
        <src file="PROGRAMS/GB/ADMIN.src"/>
        <src file="PROGRAMS/GB/libAD.src"/>
    </library>
    <program name="GB/INIT">
        <uselibrary name="CoreFunctions"/>
        <src file="programs/GB/INIT.src"/>
    </program>
    <program name="GB/LDMOD">
        <uselibrary name="CoreFunctions"/>
        <src file="programs/GB/LDMOD.src"/>
    </program>
    <program name="GB/MENU">
        <uselibrary name="CoreFunctions"/>
        <uselibrary name="Administrator"/>
        <uselibrary name="CommercialGlobal"/>
        <src file="programs/GB/MENU.src"/>
    </program>
</build>

XML Elements

Command line switches

These may be listed with kmake -?

Exit codes

When kmake terminates it indicates success or failure by setting an exit code which can be tested as the return value of SHELL. There are predefined KCML constants for these:

Generated code

If the build needs to include libraries or programs that are themselves generated by KCML programs then there should be a generated tag specifying the source file that is generated and the KCML program or XML and XSLT transform pair to do it. This generated code may be later used as source code to build other programs or libraries. The child element gensrc is used in place of src to specify a generated source file component in library and program elements.

Generating code from a program

For example, in the build file fragment below, the program WPGEN is compiled as a consequence of the program tag. The generated tag causes it to be executed by a child KCML process launched by kmake with the command-line argument GENSRC/PLUGINS.src (with path attached). This program should create and write the file specified (use $ARG() to get command-line arguments). It must return an exit code using $END with one of the same KCML constant values used by kc. Following that the library PLUGINS can be generated using GENSRC/PLUGINS.src as one of the component source files.

<-- compiles the generating program WPGEN.kbin -->
<program name="WPGEN">
	<uselibrary name="BaseFunctions2"/>
	<src file="WPGEN.src"/>
</program>
<-- Causes generating program WPGEN.kbin to be run to produce GENSRC/PLUGINS.src -->
<generated name="GENSRC/PLUGINS">
	<uselibrary name="WPGEN"/>
</generated>
<-- Builds a library  that exposes the code in GENSRC/PLUGINS.src -->
<library name="Plugins" desc="Plugins Library">
	<gensrc name="GENSRC/PLUGINS"/>
	<src file="PROGRAMS/WPMESS.src"/>
</library>

The GENSRC subdirectory mentioned in the example is presumed to exist in the $KBIN directory but it will be silently created if necessary.

Generating code using xml data and xslt

Alternatively an xslt transform may be used to transform an xml file to generated src code. In the following simple example, xml and xslt files convert the data to a sequence of function calls.

<!-- build fragment -->
<generated name="GENSRC/DATA">
	<xml file="data.xml"/>
	<xslt file="data.xslt"/>
</generated>

data.xml

<?xml version="1.0"?>
<data>
	<contact name="David" telephone="01234 111111"/>
	<contact name="Peter" telephone="01234 222222"/>
</data>

data.xslt

<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
	<xsl:output method="text"/>
	<xsl:template match="/">
		<xsl:value-of select="'&#x0a;DEFSUB 'AddContacts()&#x0a;'"/>
		<xsl:call-template name="rules"/>
		<xsl:value-of select="'&#x0a;ENDSUB&#x0a;'"/>
	</xsl:template>
	<xsl:template name="rules">
		<xsl:for-each select="//data/contact">
			<xsl:value-of select="''AddContact('"/>
			<xsl:value-of select="@name"/>
			<xsl:value-of select="','"/>
			<xsl:value-of select="@telephone"/>
			<xsl:value-of select="')&#x0a;'"/>
		</xsl:for-each select>
	</xsl:template>
</xsl:stylesheet>

The manifest

The manifest is an XML file that conditionally controls the build process. An complete example is shown below. In this example, the names CS-GB and ST-COMM are defined (by combining the UserExitCategory and UserExitCategoryCode with "-" as a separator). These names may be used in if elements in the build file. For instance <if test="ST-COMM"> would be TRUE and <if test="ST_AUTO"> would be FALSE.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Manifest>
	<UserExits>
		<UserExitCategory Name="CS">
			<UserExitCategoryCode>GB</UserExitCategoryCode>
		</UserExitCategory>
		<UserExitCategory Name="ST">
			<UserExitCategoryCode>COMM</UserExitCategoryCode>
		</UserExitCategory>
	</UserExits>
</Manifest>