KJam Reference

Usage

KJam [ -a ] [ -b ] [ -C ] [ -e ] [ -g ] [ -n ] [ -q ] [ -v ] [ -y ] [ -X ] [ -S ]
     [ -c path ]
     [ -d debug ] 
     [ -f inputFile ] 
     [ -h indent ] 
     [ -j jobs ] 
     [ -o outputFile ] 
     [ -s var=value ] 
     [ -t target ]
     [ -z [ port ]]
     [ -l power ]
     [ -x type ]
     [ -p subnet ]
     [ -i [ port ]]
     [ -P [ file ]]
     [ -L [ file ]]
     [ target ... ]

Description

KJam is a program construction tool, like make. KJam's design is based on Jam.

KJam recursively builds target files from source files, using dependency information and updating actions expressed in a user-provided jamfile, which is written in KJam's own interpreted language.

Command Line Options

If target is provided on the command line, KJam builds target; otherwise KJam builds the target 'all'.

Build Options: These options are available when KJam is running as a build client.

Network Options: These options control distributed nework building for servers and clients

Common Options: These options apply when running as both client and server.

Operation

KJam has four phases of operation: start-up, parsing, binding, and updating.

Start-up

Upon start-up, KJam imports environment variable settings into KJam variables. Environment variables are split at blanks with each word becoming an element in the variable's list of values. Environment variables whose names end in PATH are split at $(SPLITPATH) characters (e.g., ":" for Unix).

To set a variable's value on the command line, overriding the variable's environment value, use the -s option. To see variable assignments made during KJam's execution, use the -d varSet option.

Parsing

In the parsing phase, KJam reads and executes the user provided jamfile. It is written in the KJam language. The purpose of the jamfile is to name built target and source files, construct the dependency graph among them, and associate build actions with targets.

Binding

After parsing, KJam recursively descends the dependency graph and binds every file target with a location in the file system.

Any string value in KJam can represent a target, and it does so if the depends or includes rules make it part of the dependency graph. Build targets are files to be updated. Source targets are the files used in updating build targets. Build targets and source targets are collectively referred to as file targets, and frequently build targets are source targets for other build targets. Pseudo-targets are symbols which represent dependencies on other targets, but which are not themselves associated with any real file.

A file target's identifier is generally the file's name, which can have a full path, a path relative to the directory of jam's invocation, or simply local (no directory). Most often it is the last case, and the actual file path is bound using the $(SEARCH) and $(LOCATE) variables.

The use of $(SEARCH) and $(LOCATE) allows KJam to separate the location of files from their names, so that jamfiles can refer to files locally (i.e. relative to the jamfile's directory), yet still be usable when jam is invoked from a distant directory.

After binding each target, KJam determines whether the target needs updating, and if so marks the target for the updating phase. A target is normally so marked if it is missing, it is older than any of its sources. This behavior can be modified by the application of special built-in rules.

During the binding phase, KJam also performs header file scanning, where it looks inside source files for the implicit dependencies on other files caused by C's #include syntax. This is controlled by the special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is formed into a rule invocation, with the scanned file as the target and the found included file names as the sources. Note that this is the only case where rules are invoked outside the parsing phase.

Updating

After binding, KJam again recursively descends the dependency graph, this time executing the update actions for each target marked for update during the binding phase. If a target's updating actions fail, then all other targets which depend on that target are skipped.

The -j flag instructs jam to build more than one target at a time. On multiprocessor systems, or in when running in network mode this can result in a significant performance improvement. If there are multiple actions on a single target, they are run sequentially. The -g flag reorders builds so that targets with newest sources are built first. Normally, they are built in the order of appearance in the jamfile.

Language

Overview

KJam has an interpreted, procedural language with a few select features to effect program construction. Statements in KJam are rule (procedure) definitions, rule invocations, updating action definitions, flow-of-control structures, or variable assignments.

Variables

All KJam variables are one-dimensional lists of arbitrary strings. They arise as literal (whitespace-separated) tokens in the jamfiles, as the result of variable expansion, or as the return value from a rule invocation.

Rules

The basic KJam language entity is called a rule. A rule is simply a procedure definition, with a body of KJam statements to be run when the rule is invoked.

Rules take up to any number of named arguments and can have a return value (a single list). A rule's return value can be expanded in a list by enclosing the rule invocation with [ ].

The syntax of rule invocation makes it possible to write jamfiles that look a bit like makefiles.

Actions

A rule may have updating actions associated with it. Actions also take any number of named arguments. For purposes of determining dependencies, the first argument is interpreted by KJam as a list of targets, and the second argument as a list of sources. Actions also contain a script consisting of operating system shell commands to execute when updating the built targets of the rule.

When a rule with updating actions is invoked, those actions are added to those associated with its built targets before the rule's procedure is run. Later, to build the targets in the updating phase, the actions are passed to the OS command shell, with the input arguments expanded into the text of the script.

Statements

KJam's language has the following statements:

rulename arg1 : arg2 : ... : argN ;

action [ modifiers ] rulename [ : args ] [ on typelist ] {% commands %}

break

continue

export varnames

for ( var in list ) { statements }

if ( cond ) { statements } [ else { statements } ]

include file ;

[local] varnames [ on targets ][ ( = | += | -= | ?= ) values ] ;

        variable = values ;

        local variable = values ;

        variable on target = values ;

        var1 var2 var3 = value1 value2 ;

        VARNAME = var1 var2 var3 ;
        $(VARNAME) = value1 value2 ;

on target { statements } ;

return values ;

rule rulename [ : args ] { statements }

switch ( value )
{
case pattern1 : statements ;
case pattern2 : statements ;
...
default : statements ;
}

while ( cond ) { statements }

Variable Expansion

During parsing, KJam performs variable expansion on each token that is not a keyword or rule name. Such tokens with embedded variable references are replaced with zero or more tokens. Variable references are of the form $(v) or $(v:m), where v is the variable name, and m are optional modifiers.

Variable expansion in an action's command script is similar to variable expansion in statements, except that the action string is tokenized at whitespace regardless of quoting.

The result of a token after variable expansion is the product of the components of the token, where each component is a literal substring or a list substituting a variable reference. For example:

        $(X) -> a b c
        $(X) -> ta tb tc
        $(X)z -> az bz cz
        $(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c

The variable name and modifiers can themselves contain a variable reference, and this will be part of the product as well:

        $(X) -> a b c
        $(Y) -> 1 2
        $(Z) -> X Y
        $($(Z)) -> a b c 1 2

Because of this product expansion, if any variable reference in a token is undefined, the result of the expansion is an empty list. If any variable element is a null string, the result propagates the non-null elements:

        $(X) -> a ""
        $(Y) -> "" 1
        $(Z) ->
        _$(X)$(Y)_ -> _a_ _a1_ __ _1_
        _$(X)$(Z)_ ->

Individual elements of a variable, or a subsection of the elements of a variable can be referred to using []:

        $(X) -> a b c d e f g
        $(X[0]) -> a
        $(X[2]) -> c
        $(X[2-4]) -> c d e
        $(X[3-]) -> d e f g
        $(X[1,3,5-]) -> b d f g

When getting the value of a variable, the returned value can be modified by referring to the variable through the use of modifiers. Many modifiers consist of a single letter which normally selects a subset of each value. Some modifiers are followed by =, and an argument. Many modifiers only make sense if the variable string can be interpreted as a file name. A variable reference may include any number of modifiers.

The modifiers are:

The following modifiers make it possible to select or replace parts of any element which match any part of a given regular expression, by using a combination of the N modifier a numbered modifier:

Some modifiers accept or require arguments. To give a modifier an argument follow it with = and the text of the argument like so:

         SOURCES = foo.c bar.c ;
         OBJECTS = $(SOURCES:S=.o) ;
         # $(OBJECTS expands to foo.o bar.o

All text following the = is considered to be part of the argument until the expansions closing ). To express arguments with special characters, or to have multiple modifiers with arguments they must be quoted with " or ' like so:

        TEXT = foo bar goo ;
        TEXT2 = $(TEXT:N="oo"0="xx") ;
        # $(TEXT2) expands to fxx bar gxx

        TEXT = "foo=" "bar=" "goo=" l
        TEXT2 = $(TEXT:N='='0='+') ;
        # $(TEXT2) expands to foo+ bar+ goo+

Modifier arguments may themselves include variable expansions with their own modifiers. When a modifier argument expands to more than one element, only the first element will be used as the modifier argument. For example:

         EXT = bmp png jpg ;
         SOURCE_IMAGES = pony.mdl horse.mdl monkey.mdl ;
         IMAGE_FILES = $(SOURCE_IMAGES:BS="$(EXT)") ;
         # $(IMAGE_FILES) expands to pony.bmp horse.bmp monkey.bmp 

In network mode, when variables are expanded this way, the variable settings used will be those on the server. This is also the way to expand using the environment variables as they are set in the spawned command shell. For example, to set an environment variable and then echo out its value:

         {%
                  shellvar = foo
                  echo $!(shellvar) 
              %}

Literal Expansion

In the same way that modifiers can be applied to variables they can also be applied to literals. You can specify a literal either by using its name directly, in quotation marks, or surrounded by @( and ). For example the following three lines are equivalent:

        LITERAL = string ;
        LITERAL = "string" ;
        LITERAL = @(string) ;

Using the third form allows for the use of modifiers. For example to uppercase a string literal:

        LITERAL = @(string:U) ;

To get the directory where a certain literal file can be found:

        MYFILE_DIR = @(myfile.txt:FD) ;

Variable expansions and literal expansions can be nested in each other. By combining literal and variable expansions with modifiers extremely powerful expressions can be specified. For example to find all the directories where log files with a certain name and different file extensions can be found:

        LOGFILE_EXT = .log .txt .out ;
        MYFILE_DIRS = @(myfile$(LOGFILE_EXT):FD) ;

Like variable expansion, literal expansion may be done on the server using @!(. In most cases this functions exactly like normal literal expansion and is only useful in combination with variable server expansion, that is with $!(.

Grist

      TESTS = <project1>test.data <project2>test.data ;

Built-in Rules

KJam has 11 built-in rules, all of which are pure procedure rules without updating actions. They are in three groups. The first builds the dependency graph. The second modifies it, and the third are utility rules.

Dependency Building: The following rules are used to explicitly add links to the dependency graph.

depends targets1 : targets2 ;

include targets1 : targets2 ;

    depends  foo.o : foo.c ;
    includes foo.c : foo.h ;

cleardep targets ;

clearinc targets ;

Modifying Binding: The six rules always, leaves, notfile, noupdate, and temporary modify the dependency graph so that KJam treats the targets differently during its target binding phase. Normally, KJam updates a target if it is missing, if its file system modification time is older than any of its dependencies (recursively), or if any of its dependencies are being updated. This basic behavior can be changed by invoking the following rules:

always targets ;

leaves targets ;

nocare targets ;

notfile targets ;

noupdate targets ;

temporary targets ;

Utility Rules: The remaining rules are utility rules.

echo args ;

print args ;

exit args ;

Built-in Variables

KJam has several special variables which change the behavior of the program.

SEARCH and LOCATE Variables

These two variables control the binding of file target names to locations in the file system. $(SEARCH) is used to find existing sources while $(LOCATE) is used to fix the location for built targets.

Rooted (absolute path) file targets are bound as is. Unrooted file target names are also normally bound as is, and thus relative to the current directory, but the settings of $(LOCATE) and $(SEARCH) alter this.

The $(SEARCH) path can be defined using wildcard characters to match multiple directories:

      $(SEARCH) = obj/*/debug ;

HDRSCAN and HDRRULE Variables

These two variables control header file scanning. By using $(HDRSCAN) and $(HDRRULE) it is possible to eliminate the need for an explicit dependency making step, or the use of external dependency building tools such as makedepend.

When $(HDRSCAN) is set "on" a target, if that target is a file, KJam will scan that file for inclusion statements. The value of $(HDRSCAN) should be set to a regular expression which matches inclusion lines in the given source file. The pattern should match the entire inclusion statement. The pattern should include a single () grouping which indicates the filename being included.

Whenever a match is found by KJam using $(HDRSCAN), KJam will invoke a the rule named by the $(HDRRULE) variable. Typically this allows the user to create a rule to recursively scan files for inclusion and to build the dependency graph.

Both $(HDRSCAN) and $(HDRRULE) must be set for header file scanning to take place, and they should be set target-specific and not globally. If they were set globally, all files, including executables and libraries, would be scanned for header file include statements. Careful use of these variables allows for different $(HDRSCAN) patterns to be used for different source file types.

The $(HDRSCAN) and $(HDRRULE) variables must have the same number of elements. Normally, if there is only one pattern to scan for a given file type, then both variables will be set to lists with a single element. But this it not requires. You can set these variables to lists with multiple elements. This will cause the header scanning to use multiple regular expressions, and to call a different rule for each pattern. This can be useful for languages with more than one type of inclusion directive, and where the different types of inclusion directives must be treated differently.

The scanning for header file inclusions is not exact. The scanning mechanism errs on the side of inclusion. That is, it is more likely to return filenames that are not actually used by the compiler than to miss include files because it can't tell if #include lines are inside #ifdefs or other conditional logic. It is normally a good idea to apply nocare to each header file found during scanning so that if the file isn't found it doesn't cause the compilation to fail.

Scanning for regular expressions only works where the included file name is literally in the source file. It can't handle languages that allow including files using variable names (as the KJam language itself does).

JAM_SHELL Variable

By default KJam uses its own internal sh-like shell. This allows KJam command scripts to run in a common execution environment no matter what shells are installed on the target platform. The built-in shell may not be appropriate for all applications. To call out to a specific operating system shell, a jamfile may set the $(JAM_SHELL) variable:

        JAM_SHELL = /bin/sh -c % ;

The % is replaced with the text of the command script. If % is not provided, the text of the command script is added at the end.

Jam Version Variables

Built-in Shell

KJam uses its own built-in sh-like shell to execute command scripts during the updating phase. The KJam shell separates the script into command chains on newline boundaries. Each command chain consists of a series of operating system commands separated by | pipe operators. Each command is passed to the operating system and run. Its output stream is redirected to the input stream of the next command in the chain. The error stream of each command is redirected to a common error stream for the command chain. If any command returns a non zero return code, all of the commands in the chain are terminated and the shell will return this error code.

The output and error streams of the command chain may be redirected to one another or to a file by appending one of the following to the end of the command chain:

Any output redirected to a file named nul will cause that output to be deleted.

A command chain may take its input from a file by use of input redirection:

The built-in shell includes several built-in commands which the shell interprets itself, instead of calling out to the operating system.

These built-in commands may mask existing commands on your system. To use the operating system versions, a complete path to that command, an alias or simply surround the command name in quotes, or run your script using the operating systems own shell.

Comments begin with # and continue to the next newline character.

The KJam shell is very limited, and supports only the shell features normally used in short command scripts found in make files. For example it does not have support for flow control, like sh's if, do, while and case statements.

To set shell varibles use =, like so:

      foo = bar

      echo $!(foo)

chmod

This tool changes the file permissions. Command takes arguments of the form:

The -R option changes the permissions of all files and subdirectories under a given directory. The -f option will cause chmod to not issue errors concerning file permissions if any are encountered.

The mode can either be an octal number representing the actual bit pattern of the file persmissions, or a symbolic mode of the form:

Where who is one of: u, g, o, a, which represents setting permissions for user, group, other or all respectively.

Where op is on of: +, -, which represents adding that permission or removings it respectively.

and where the permission itself is one of the following:

rgxrpl

This is a tool to manipulate text using regular expressions. The program reads data from standard input, changes it using the regular expressions given on the command line, and writes the modified data to standard output. Each command line option will either match some part or the input, or will modify matched data in some way. The command line operations are applied to the data from left to right as they appear on the command line. The operations are:

Regular Expressions

The KJam language uses regular expressions anywhere where flexible matching of text is desired. As noted above this includes using regular expressions as arguments to the X, I and N variable expansion modifiers, as the labels in a switch statement, and as the value of for the HDRSCAN built-in variable. KJam's implementation of regular expressions matches closely with the syntax of standard Posix regular expressions, and should be familiar to many users.

A regular expression consists of one or more non-empty branches separated by |. A regular expression matches any text which matches at least one of those branches. For example, the expression one|two will match the string one and the string two.

A branch consists of one or more concatenated atoms. There are several types of atoms, and each one can be used to match a given text. The types of atoms are:

By itself each atom matches exactly one copy of the matching input text. Each atom may be followed by one of the following, which changes how many times the atom matches:

A bracket expression is a series of characters enclosed in []. It normally matches any single character from the list. If the list begins with ^, it matches any single character not in the list. If two characters in the list are separated by -, this is shorthand for the full range of characters between those two in the collating sequence.

For example the atom [abc]* would match the first 5 letters of bcbacXacd. The atom [^X]* would also match the first 5 letters of bcbacXacd. The atom [A-Z0-9] would match the first 5 letters of DS14Tabc.

A bracket expression may also contain inside its [] one of the following special character classes:

For example the atom [[:alpha:]_]* would match the string this_is_a_test.

A regular expression may also contain back references. All regular expression atoms, that is any atom surrounded by () are numbered. They are numbered in the order that their ( appears in the expression. So the leftmost regular expression atom would be numbered 1, the next one 2 etc. The entire expression is numbered as zero. A back reference atom matches the exact same string as the numbered atom it refers to.

For example a(b*)c\1d matches any string with the same number of b's on either side of the c such as the following strings: acd, abcbd, abbbcbbbd.

Network Execution

KJam may be run in a distributed client-server mode over a network. In this mode, KJam is started on each machine as a server process, with the -z option. If all the servers are on the same subnet and using the default KJam network port (2297), then all the servers will find each other and organize themselves into a peer network. It is possible to create peer networks of servers on alternative ports, and across subnets by using additional command line options.

KJam is run as a network client with the -y option. In this mode by default KJam will attempt to connect to a KJam server on the local machine, on the KJam network port (2297). It will run through its normal operation just like in non network mode, except when running command scripts, instead of running them locally, the scripts will be sent to be run on one of the KJam servers on the peer network. The peer network's own load balancing algorithms will distribute command scripts across the peer network. Multiple KJam clients may be interacting with the peer network at any time. By using additional command line options is it possible for the KJam client to connect to any server or port to get its initial pointer into the KJam peer network.

If KJam is started as a network client and it cannot find a peer network it will scan for one on the local subnet. While this works, it is considerably slower than either making sure there is a KJam server running on the local machine, or providing appropriate information about where one can be found.

In most cases it is important that the file system used by KJam to bind files on the local system be visible on all of the remote KJam servers in the exact same way. The commands passed to the remote servers will be run on those servers with the bindings determined on the KJam client. The files themselves are not transferred, but rather the remote server will attempt to read them from its view of the file system. Similarly, the output files and the programs being run are also not transferred. All of these things must be available on the remote server system. There are several easy ways to accomplish this. The simplest is to make the part of the file system that the KJam client is running in be visible on the network from all the machines. ( For example on windows by 'sharing' ). Then run the client in the subdirectory using the shared version of the directory. ( e.g. //SYSTEMNAME/PROJECTNAME ). In unix file systems this problem should be easier to address if all of the machines have had their local file systems mounted into one large virtual file system.

In network mode, special attention should be paid to the configuration of compilers and the versions of libraries and headers on all the KJam servers. It is possible with subtle changes in these tools for the build to appear to complete correctly but for the binary to have problems. It should also be noted that when running in network mode most programs will be running on one system but interacting with a file system on another. This often runs more slowly than if the entire process was local. For some programs which execute in very little time, or have heavy file access patterns it may be faster to run those command scripts entirely locally, and only distribute onto the network command scripts with more computationally intensive scripts.

Server command line options:

Client command line options:

It is possible to make KJam spawn jobs on only certain servers. To do this the servers can advertize one or more server 'types' using the -x option. Each action can be optionally labeled with a list of server types which the action can run on. When an action script has a server type, the peer network will only schedule that job to run on a server which advertizes that type. In addition to the server types specified by the -x option, KJam servers advertize several default types. All servers will advertize the local machine name as one of their types. This is so that scripts can be easily written where certain actions run only on a specifically named system. Linux machines will advertize as "Linux". All Microsoft Windows machines will advertize "Win32". Depending on the version of Windows, those machines will also advertize one of the following types: "WinXP" "Win2000" "WinNT" "Vista" "Longhorn" "Win2003ServerRc2" "Win2003Server" "Win95" "Win98" "WinME" "Win32s". Servers will also advertize the processor architecture, "i386", "i686" or "AMD64".

Case Sensitivity

The KJam language itself is always case sensitive. Case is important when referring to variables, targets, rules, and actions.

By default KJam also interacts with the file system in a case sensitive manner, even on operating systems with case insensitive file systems like Windows. In most cases, even on Windows this should produce correct behavior if the Jamfiles are written to carefully match the case of the actual file names.

In some cases this can be a problem when the same file is referred to in multiple places in the sources ( e.g. include directives ) with different cases. In this case KJam may fail to properly track some dependencies, or fail to find some targets. The preferred, cleaner solution is to fix the sources such that files are referred to with the correct case. If this is not possible KJam can be run in case insensitive mode using the -C option.

The -C option is almost never useful when KJam is running on an operating system with a case sensitive file system ( like Linux or Os X ). It can sometimes be useful on these platforms when generating build scripts for Windows using the -o option.

The -C option will cause a small performance penalty to file system scanning speed.

Managing Built-in Jamfiles

KJam comes configured with a set of built-in Jamfiles. This allows KJam to support many simple c and c++ projects with extremely simple user-defined Jamfiles.

For more complex projects most users will want to write their own custom Jamfiles. These can be written as separate Jamfiles and stored in the filesystem like regular files, or they may be embedded into KJam, replacing the built-in rules.

To extract the built-in Jamfiles, run KJam with the -X option. KJam will write out all its embedded rule files in the local directory with their original names. The KJam binary will still hold copies of the embedded files.

To replace the built-in Jamfiles, run KJam with one or more -P filename options. KJam will remove any existing embedded Jamfiles, and will embed all the files passed in through the -P option. If all the files passed in are found, and KJam is able to embed all the passed in files successfully, KJam will write out a new binary named kjam_new which has the new files embedded. This new binary will run as if all the embedded jamfiles were in the same directory as the kjam binary. Once it has been confirmed that the new binary runs correctly, it can be safely copied over the original kjam binary.

To remove all the embedded files, and replace them with nothing, use a single -P with no arguments.

Performance Considerations

KJam is designed to be able to compute dependencies between thousands of targets, and to determine which ones need to be updated in just a few seconds. Even for large projects, KJam's response time should be very fast. When writing a Jamfile the following things may adversely affect performance:

File System Latency: Each time KJam runs it must find every target in the file system, and get its time stamp. To scan for headers it may also need to read the contents of many files. If it is interacting with a slow file system, such as one which is mounted over the network, this may cause KJam to run much more slowly.

Too many directories in $(SEARCH): During the binding phase, each file is searched for in each directory specified in $(SEARCH). The number of checks scales as the product of the number of targets by the number of directories to search. For large projects with many files and directories it is important to limit the number of directories that each file is searched for. Divide up the targets into groups ( for example, by library, or separate data files from source files etc. ), and search for targets in each group in the smaller subset of directories in which they occur.

$(HDRSCAN) pattern too complex: A regular expression is used to scan files for header references. If there are a large number of files, or if the files are large the time spent scanning can be quite significant. An attempt to match each pattern is made at every byte offset in the file. That is for a 5k file, 5k matches must be attempted. Patterns where the first character in the pattern always occurs will execute much more quickly than patterns where the first element is optional. For example, the first header matching expression is much more efficient than the second one:

      HDRPATTERN = "#[\t ]*include[\t ]*[\"]([^\"]*)[\"]" ;

      HDRPATTERN = "[\t ]*#[\t ]*include[\t ]*[\"]([^\"]*)[\"]" ;

Very long files to scan: Some projects may include automatically generated source files which can be very large ( many megabytes ). It can take a significant amount of time to read in and scan these files for headers. In addition it is usually unnecessary to scan such files any further than the first few lines. To limit the how far into large files to scan set $(HDRSIZE) to the length in bytes of the depth to scan each file. Only the first $(HDRSIZE) bytes of each file will be checked. Setting this variable to zero or a non-number will cause the entire file to be scanned.

Overuse of flow control: Many things which are possible to do with flow control constructs like for and while can be done faster by use of expansion modifiers. For example:

      for ( I in $(C_FILES) ) { O_FILES += $(I:S=".o") ; }

      O_FILES = $(C_FILES:S=".o") ;

Re-evaluating expansions unnecessarily: In KJam it is much more efficient to create a new temporary variable than to re-evaluate a variable expansion. For example, the following code:

      LOCATE on $(TARGET) = $(BIN_DIR)$(OBJ_SUBDIR) ;
      depends $(TARGET) : $(BIN_DIR)$(OBJ_SUBDIR) ;

      OUTPUT_DIR = $(BIN_DIR)$(OBJ_SUBDIR) ;
      LOCATE on $(TARGET) = $(OUTPUT_DIR) ;
      depends $(TARGET) : $(OUTPUT_DIR) ;

Diagnostics

In addition to generic error messages, KJam may emit one of the following:

warning: unknown rule X

updating N target(s)

can't find N target(s)

can't make N target(s)

warning: X depends on itself

don't know how to make X

X skipped for lack of Y

Warning: Target X will be built as a side effect of building another target.

Bugs and Limitations

A poorly set $(JAM_SHELL) is likely to result in silent failure.

Actions set with the 'together' modifier may not have more than three arguments.

When building in parallel sometimes the tools which KJam calls may try to access a file while it is being accessed by another tool in another thread or process. This may cause some of these programs to fail due to a file being locked or busy. KJam itself always checks for these conditions and should never have problems with files which are temporarily locked or busy. Some tools however do not check for this condition and may in rare instances fail unpredictably. The only way to fix this problem would be to rewrite those tools to interact with the file system more carefully.

KJam's dependency scanner is regular expression based. It can be used to create dependency scanners which trigger off simple include expressions, but cannot be used to evaluate inclusion statements which are affected by macros. Therefore it is possible for KJam to generate extra dependencies for included files which in reality are not actually included because the include statement is controlled by a conditional statement. It is often the case that conditionally included files may not actually exist on some platforms resulting in missing file errors. If this is the case, these errors can be silenced by labelling those files as nocare. In a correctly written jamfile this can only result in extra dependencies, and never in missing dependencies. It is possible if a jamfile has incorrectly set search paths for an include file which is necessary to not be found and yet for an error not to be generated because the header file was labeled nocare. This results in missing dependencies which can affect the correctness of builds. When jamfiles are being developed which include the keyword nocare, this condition should be checked for by running the KJam with the -d search command line option, and the list of files not found should be carefully checked for correctness.