Documentation for Build v2.08
Table of Contents

Pragma

The build utility supports the use of various pragma statements.


A pragma is a special statement embedded in the source code that provides information to tools reading the source code.

They take the forms ...

 pragma( <name> );
 pragma( <name> , <option> [ ,<option>] );

If the D compiler doesn't recognise the pragma, it will fail. So to 'hide' them from the compiler, you need to wrap them in a version block. All the pragmas used by this utility need to be enclosed in a build version.

Example:

version(build) { pragma(nolink); }

  • pragma build   This identifies a file that needs an external program to build it.
  • pragma build_def   This supplies an option to be placed in an OptLink definition file.
  • pragma include   This identifies a required file which is not otherwise imported.
  • pragma link   This nominates one or more libraries that are required to be linked in.
  • pragma nolink   This identifies that the current module is not to be be linked in.
  • pragma target   This identifies the basename of the target file.

    Documentation for Build v2.08
    Table of Contents

    [pragma]
    build

    This identifies a file that needs an external program to build it.

    Category: Pragma

    Some applications need to link in object files created by C source, or by a resource compiler, or whatever. This pragma identifies a file that needs to be linked in, but cannot be created by the D compiler. The format is

    pragma(build, "FILENAME" [, "OPTIONS"] ...);
    
    where FILENAME is either the file to link in, or the file to use when creating the file to link in. For example, if you had a Windows resource file that needed to be compiled, you could code the pragma as either ...

     /// Compile the images into a resource obj and add images.res to linker.
    pragma(build, "images.rc");
    
    or
     /// Compile the images into a resource obj and add images.res to linker.
    pragma(build, "images.res");
    

    The first example specifies the source file to be passed to the resource compiler and the second example specifies the output of the resource compiler. In either case, this utility uses the rules in a Rule Definition File to decide what to do.

    The utility searches for the FILENAME in the currently defined 'import' paths.

    The OPTIONS can be included if you need to pass any special values to the external tool. There can be any number of these, but each one must take the form <KEYWORD>=<VALUE>. For example

    pragma(build, "dbapi.c", "COPT=-wc -x", "HDR=abc.hp");
    
    The OPTIONS values are used as replacement text for token in the Rule Definition File's 'tool' specification. In the example above, the tokens {COPT} and {HDR}, if found in the 'tool' line, would be replaced with -wc -x and abc.hp respectively.

    The output file to the external tool is checked to see if it is still up to date.

    The output file from the external tool is added to the linkage set.

    All such external programs are run before the D compiler is invoked.

    Example:

     /// Tell 'build' that it needs to call an external program
     /// to build an up-to-date version of 'images.rc'
    version(build) { pragma(build, "images.rc"); }
    

    See Also: build_def, include, link, nolink, target


    Documentation for Build v2.08
    Table of Contents

    [pragma]
    build_def

    This supplies an option to be placed in an OptLink definition file.

    Category: Pragma

    You can have build create a customised OptLink definition file by coding as many build_def pragmas as required. However, build will only allow the first of each type of Definition File command to be used. THis means that if you code ...

    pragma (build_def, "EXETYPE DOS");
    pragma (build_def, "EXETYPE NT");
    
    Then the EXETYPE DOS will be used and the 'NT' line ignored. You can use explicit build_def pragmas to override the default ones generated by build for Windows programs or DLL libraries.

    The syntax for these pragma is

    pragma(build_def, <QUOTED_STRING> );
    

    Example:

    version(build) {
    pragma (build_def, "VERSION 1.1");
    version(DOS) {
    pragma (build_def, "EXETYPE DOS");
    }
    version(WIN) {
    pragma (build_def, "EXETYPE NT");
    pragma (build_def, "SUBSYSTEM WINDOWS,4.0");
    }
    }
    

    You can supply any text string and it is used verbatim. There is no restrictions on what you can include in the pragma.

    See Also: build, include, link, nolink, target


    Documentation for Build v2.08
    Table of Contents

    [pragma]
    include

    This identifies a required file which is not otherwise imported.

    Category: Pragma

    In some applications, especially ones converted over from C, it is possible that the file on the Build command line does not directly or indirectly import a required file. In those situations, you can use this pragma to tell build to include it in the compilation checking process.

    Example:

     / Tell 'build' that prime.d must be included (it contains the main function.)
    version(build) { pragma(include, "prime"); }
    

    See Also: build, build_def, link, nolink, target


    Documentation for Build v2.08
    Table of Contents

    [pragma]
    link

    This nominates one or more libraries that are required to be linked in.

    Category: Pragma

    If your applications needs code from a library to be linked in, rather than supplying source code, you can tell build which libraries are needed. This can happen when using a library provided by a third-party.

    Example 1:

     // This app needs the MyGUI.lib library to be used.
    version(build) { pragma(link, MyGUI); }
    

    Example 2:

     // This app needs the a DB library and TCP library to be used.
    version(build) { pragma(link, EuDB, TCP4Win); }
    

    See Also: build, build_def, include, nolink, target


    Documentation for Build v2.08
    Table of Contents

    [pragma]
    nolink

    This identifies that the current module is not to be be linked in.

    Category: Pragma

    Normally, each object file created by the compiler is linked in, but if the supplied source file is just a stub for code which is externally defined in a library, then you do not need the 'stub' object file.

    Example:

    version(build) { pragma(nolink); }
    

    See Also: build, build_def, include, link, target


    Documentation for Build v2.08
    Table of Contents

    [pragma]
    target

    This identifies the basename of the target file.

    Category: Pragma

    By default, the target name is based on the first file on the command line. But if you include this pragma, the name identified in the pragma becomes the default name. In either case, the -T switch overrides the default name.

    If two or more target pragmas are found, the first one is the one that is used and the others are ignored (though mentioned if in verbose mode). Example:

     /// Tell 'build' to create WhizzBang.exe
    version(build) { pragma(target, "WhizzBang"); }
    

    See Also: build, build_def, include, link, nolink