ZmakeGen

Topic:.ZmakeGen.translator.

pStyle=std tableStyle=stdTable

The Zmake translator translates between a Zmake user script and the ready-to-run make-script. The zmake user script describes what's how to make in a more simple syntax than most of the other known make scripts. The outputted make-script may be an ANT.xml-make file, an old-style make file, a simple batch or script file or any other control file for a make process. The translator is able for universal usage, it controls which text is produced for the output.

 Zmake
 user    =====Z===translator=====> make script
 script       ^        ^           ready to run
              |        |
              |        |  (user level)
         - - -|- - - - |- - - - - - -
              |        |  (admin level)
         zmake.zbnf    |
                       |
  ZmakeGenctrl.zbnf--->Z
                       |
              translation script

The Zmake translator works in two stages. Adequate, two scripts control the working of the translator:

Parsing the Zmake user script: A Zmake.zbnf syntax script describes the syntax of the zmake user script and controls the ZBNF-parser.
Generate the output script: The translation script controls it. The translation script is parsed too before it is used. The zbnfjax/xsl/ZmakeGenctrl.zbnf contains the syntax for it.

The three scripts below are designated as 'admin level' in the figure above. Where the end user writes its Zmake script and starts the make process for its sources, a person which administrates the make-tools edits and determines the translation script. The translation script can contain some more options for the compiler or other translator tools, which are usage specific, but without influence possibility of the end-user. For example some standard include paths or compiling options may be determined from the administrator only. The translation script may be usage-unspecific also, whereby all options are supplied in the user script.

The zbnfjax:xsl/ZmakeStd.zbnf script determines the syntax and semantic of the user script. The given script containing in zbnfjax/zmake/zmake.zbnf contains enough possibilities to formulate the users requests. It is adjusted with the Java-algorithm of the translator. But some enhancements are possible without changing the translator-program.

The zbnfjax:xsl/ZmakeGenctrl.zbnf controls the syntax of the translation script. It is adjusted with the internals of the translator. Only for special cases an adaption may be sensitive.

The translator itself, a Java-program, is not specialized to any input or output form.

2 Example compiling/build lib with a batch file

Topic:.ZmakeGen.exampleBatchCC.

pStyle=std tableStyle=stdTable

The request of this example is: Compile some files and build a lib. A simple way to do so is: Using a batch file, which calls the compiler for any file, after them calls the libriary builder. The advantage of such a simple batch or shell-script file is: The user see what's happen. There aren't any conditions and complexity in opposite to a make-system. But the disadvantage of that strategy is: The batch file contains many lines with adequate content, only the file names are different. If any compiler-option should be changed, then all lines should be corrected. - The batch-schema is used as a simple example here to show the principle of Zmake.

The disadvantage, writing adequate lines with repeated content, can be resolved by Zmake. See the user's input script:

ZMAKE_RULES:
$CfilesCommon = fileset(
  source:OSAL/os_common.c
, source:OSAL/Reflection_OSAL.c
);
$CfilesOsSpecific = fileset( srcPath=source/os_Windows
, os_sync.c
//, os_fileLoLevel.c
, os_file.c
, os_atomic.c
, os_thread.c
, os_endian.c
, os_mutex.c
, os_socket.c
, os_mem.c
, os_error.c
, os_time.c
);
$includePath = fileset
( include
, include/OSAL
, includeSpecials/os_Windows
, includeSpecials/FwConvC32
);
OSALJc := buildLib($CfilesCommon, $CfilesOsSpecific, include=$includePath);

The users source script contains only necessary information and only one time per information:

The input files to translate: Here are used two blocks, common and os-specific. There are given with a path.
The include path used as compiler option: That is the most variable option for the compiling process.
All other compiler options may be fix and therefore not determine at this user level.
The last line is need to build the lib. It is a Zmake-target. The inputs and options are given as inputs.

For the zmake.zbnf script the xsl/zmakestd.zbnf is used. It allows the shown notation.

The translation script contains the prescript, how the batch file is to built. Look at it:

<:target=buildLib>
<:forInput>
  <:>
  echo compile (?input.name>
  cc -option -o obj\(?input.name>.o (?input.file>
  <.>
<.forInput>
 <:>
 echo call of library building
 libc -optionLib <:forInput><:>obj\(?input.name> <.><.forInput>
 <.>
<.target>
<:file>
  <:>
@echo off
<*target>
<.>
<.file>

The translation script contains two blocks:

The prescript for the Zmake-target 'buildLib'
The prescript to build the whole file.

The whole file starts with

@echo off

That's a typical statement for a windows-batch-file. The rest of the file consists of the content of the built targets.

The target build-prescript buildLib contains:

A block <:forInput>...<.forInput>. The lines between them determine the lines which are produced by this target for any input file. It contains the compiler call with all options and the input file. Some parts are used from the input file: The full file path as input for the compiler, but only the file name for the object's name.
After the forInput-block a second part determine the lines to call the library builder.
Tne line for the libc-call contains a <:forInput>...<.forInput> block too. It is used to provide the object-file for any input as an argument for the libc-command.

This content is produced for any target of type 'buildLib' in the users Zmake-script. The users Zmake-script contains only one such target. But it's possible to have more as one. The produced lines for all targets are stored internally, and they are outputted if <*target> is specified in the file's content.

The responsible person for the compilation process can intend now all options for compiling. Only one time in one line of the Zmake-generating script, not in all lines of the users script may be for more as one library.

The output of this Zmake-translation-action is (shortened)

 @echo off
 echo compile os_common
 cc -option -o obj\os_common OSAL/os_common.o
 ...
 echo compile Reflection_OSAL
 cc -option -o obj\Reflection_OSAL OSAL/Reflection_OSAL.c
 ...
 echo compile os_sync
 cc -option -o obj\os_sync os_sync.c
 ...
echo call of library building
libc -optionLib obj\os_common obj\Reflection_OSAL obj\os_sync obj\os_file obj\os_atomic obj\os_thread obj\os_endian obj\os_mutex obj\os_socket obj\os_mem obj\os_error obj\os_time

The options are shown only in a symbolic way in this example. Write the necessary compiling and lib options instead.

3 Syntax of the user Zmake script

Topic:.ZmakeGen.syntaxZmakeStd.

pStyle=std tableStyle=stdTable

A user zmake script can start with any textual content. For example it starts with script commands of a shell or windows batch file. The zmake content starts after a key line:

ZMAKE_RULES:

After them some Target or Variable can be placed. A Target is a rule to make something. A Variable contains file names or texts.

The order of the Targets can determine the order of execution. It depends of the translation script how it is used. If a simple batch file will be generated, it is the order of execution. If a make file is generated which knows dependencies between the targets, then that rules are valid.

A target is written in the form:

[:targetName:] outputfile := translator ( { input ? , } );

The targetName is optional. By default a name is build with the String of outputfile. A name may be necessary if either the same outputfile is given twice for ANT-script-generation, or special restrictions should be obtained for the name.
The translator should be known by the translation script to generate the ready-to-run make file. It is an identifier such as 'cc'.
The outputfile may contain wildcards, it may have a relative or absolute path or a local path. Its syntax of file::= is described below. The translation script decides the usage of parts of the outputfile.
The input is translator-specific. It may be some variables or some file-pathes or texts etc. It is translator-specific. The translation script can be use parts of the input or the outputfile in a specific way.

A variable which presents a fileset is written in the form:

$name = fileset( [{ srcpath = sourcepath | srcext = sourceext ? , } , ] { file ? ,}

The sourcepath and the sourceext are optional. It determines a common source path and/or common extension for all files of the set. The files can be written with absolut or relativ path, with a local path part and maybe with wildcards. The syntax is:

file::=[ basepath:]localpath/file.ext

The basepath is optional and can be a relative or absolute path. It can contain the drive letter for windows file systems. The localpath is recognized as an integral part of the file pathname. A generated scrip can handle with the localpath.file.ext non considering the basepath for example to replace a wildcard part of an outputfile. The separator : between basepath and localpath replaces a /.

The path can be written with slash or backslash for Windows applications. On Windows the slash is able to use too. It should be recommended.

There are some additional possibilities in the syntax script zbnfjax:xsl/ZbnfStd.zbnf, which were used in the past with ANT-Generation using XSLT. That features are not supported yet for Zmake Java script generation, but may be supported in the future. That are:

specials as target like mkdir,deltree which should produce os-specific file system operations.
exec produces calling of any command line invocation.
for ( <input> ) <routine?doForAll>, where routine is another target or an exec.

4 Syntax of the translation script

Topic:.ZmakeGen.syntaxZmakeGenctrl.

pStyle=std tableStyle=stdTable

The translation script is similar like XSLT. But instead <xsl:name>...</xsl:name> there is used a notification with one of the control chars after < and with <.TAG> instead </TAG>. That abbreviated notification should support a better separation between script control content and textual content if a XML output should be produced (ANT). The basic forms are:

<: control construct
<* access to content of a variable, container, input, list-element
<. end marker
<= set of a variable
<+ add content to a container
<. end tag.

The following notification are available:

<:target = NAME> CONTENT <.target>:: It describes how a target should be generated. In the users script the target is written in form:

dst := NAME(parameter);

<:for:NAME>...<.for>: It is a control construct. The text between the tags is produced for each files of the fileset, which is designated with the named parameter. The parameter is a parameter of the target. The input file-path parts can be accessed with (?*name.part>, whereby NAME is the same name like used in the <:for:name>. It is similar to <xsl:for-each ...>....
<:forInput>...<.forInput>: It is a control construct. The text between the tags is produced for each input files of the target. The input file-path parts can be accessed with (?input.part>. It is similar to <xsl:for-each ...>....
<:forList:name>...<.forList>: It is a control construct. The text between the tags is produced for each element of the named list. The list-element-content can be accessed with (?*>. It is similar to <xsl:for-each ...>....
<:text>...<.text>: The text between this tags is used without any interpretation. Both white-spaces and all other characters are transfered in the output. It is similar to <xsl:text>...</xsl:text>.
<=name>...<.=>: It is a definition of a variable similar to <xsl:variable name="...">.... The text between the tags defines the constant value of the variable.
<*name>: Access to a value of a variable or a value of input or output files. It is simular to <xsl:value-of.../>
<+name>...<.+>: The value between the tags are added to the named list-container instead to the output or to the target container. The container is filled. Its content can be accessed using <:forList>...<.forList>. This mechanism is not present for XSLT.
<*> presents the content of the current list element in a <:forList>...<.forList>-sequence.
<*name.part> presents the content which is build with a <:for:...>-element. The part is optional. it designates the part of a file path.
<:>...<.>: The text-content between this tags are written in the output with all whitespaces. The content can contain all control elements in <...> which produces an output text. They are regarded and expand (in opposite to (?text>...<.text>).

The formal syntax is contained in file:Zmake/ZmakeGenctrl.zbnf. The translation script will be parsed with ZBNF before it is used for synthetizing. Therefore that zbnf-syntax describes how the translation script is understand. To understand better for human, follow the examples.

4.1 Access to file parts

Topic:.ZmakeGen.syntaxZmakeGenctrl..

pStyle=std tableStyle=stdTable

A file can be written in the users script for example with

path:localpath/name.ext

The parts of a given path can be used in the translation script. The translator prepares the file name, path etc. with this parts and maybe with the given TODO in form of:

<:file> builds the whole file path but without building an absolute path.
<:dir> (TODO) builds the directory where the file is contained, without ending '/'.
<:name> builds only the name of the file without extension. If the filename has more as one point, only the part after the last point is the extension. A file myfile.type.xml has the name myfile.type, the extension is xml.
<:nameExt> builds the name with the extension.
<:ext> builds the extension only.
<:localFile> builds the part of the filepath after a ':' or the given path like <:file> if a ':' isn't present.
<:localPathName> like localFile but without the extension.
<:absFile> A given relativ path is completed with the curDir, the script variable for the current directory. It is because the command-execution-specific current directory is not able to access often inside scripts. The curDir variable can be set with knowledge of the current directory while the script is started. Note: On windows the environment variable %CD% contains the current directory path as an absolute path. On UNIX systems it is the $pwd.
<:absDir> (TODO) builds the absolute path like <:absFile>, but without the file name like <:dir>

Examples: TODO

ZmakeGen

1 Zmake-translator

2 Example compiling/build lib with a batch file

3 Syntax of the user Zmake script

4 Syntax of the translation script

4.1 Access to file parts