Creating a target environment configuration file

A target environment is defined by using a configuration file (.cfg) that contains the options for this target environment. You must create a configuration file for each target environment that you plan to define.

About this task

Every z/TPF application that is built by using the MakeTPF build solution requires a configuration file. In many cases, certain configuration settings are common to many applications, for example, the root directory that stores the z/TPF source code, build options, and language options. TPF Toolkit provides you with the capability to specify those common settings and options in a target environment configuration file so that your users can specify them one time and reuse the same settings across different applications or projects without having to define them multiple times.

If your users select a target environment in the MakeTPF Configuration Editor, the configuration file of this target environment is included in the project configuration file. The MakeTPF options in the project configuration file and the target environment configuration file determine the build space of the TPF project.

Your users cannot modify target environment configuration files but can modify project configuration files. Therefore, if you do not want your users to change some particular MakeTPF options, you can define them in the target environment configuration file. If some MakeTPF options need user input or if you want to delegate some options to your users, you can include them in the project configuration file.

Procedure

  1. On your remote build server, create a target environment configuration file with a name that describes the options of your target environment, for example, cur.bss.cfg.
    Ensure that you grant read permissions to all users who need to reference the file.
  2. Define the target environment options in this file.
    As a type of configuration file, a target environment configuration file follows the format and coding conventions of configuration files in general, which are coded by using the GNU make syntax. You can use the following example to define your target environment configuration file.
    Notes:
    • At a minimum, you must include the TPF_ROOT and APPL_ROOT fields to specify the root directories where the z/TPF source code and application source code reside.
    • Depending on your build process, you can specify additional options by using the variables that are supported in configuration files.
    • You also can define your own variables and pass them to the MakeTPF Configuration Editor for your users to assign values. To pass a custom variable to the MakeTPF Configuration Editor, you must initialize this variable with a default value in the TARGET ENVIRONMENT VARIABLES section of the project configuration file. If you do not want your users to modify this variable, specify the variable outside the TARGET ENVIRONMENT VARIABLES section.
    For more information about coding configuration files and the variables that are supported in configuration files, enter man maketpf.cfg on your Linux® on IBM Z build system.

Example

The following example shows the configuration file of a target environment named CUR BSS.

# Build configuration for CUR BSS

# TPF source root directory
TPF_ROOT := /ztpf/cur

# Application source root directory
APPL_ROOT := /ztpf/curdrv

# Basic subsystem name
TPF_BSS_NAME := BSS

# gdwarf level - supported values are 0 (omit) and 2
TPF_GDWARF_LEVEL := 2

# Initialize the user flag variables
# Customize based on passed variables
ifeq ($(TKDBG),true)
  ASMFLAGS_USER := ADATA
  CFLAGS_USER   := -O0 -g
  CXXFLAGS_USER := -O0 -g
else
  ASMFLAGS_USER :=
  CFLAGS_USER   :=
  CXXFLAGS_USER :=
endif
This configuration file defines the following MakeTPF options:
  • The z/TPF source code can be found by searching the /ztpf/cur directory.
  • The application source code can be found by searching the /ztpf/curdrv directory.
  • The z/TPF system that the application will be built for is a basic subsystem with the default name BSS.
  • The application program will be compiled with the -gdwarf-2 option specified to generate information in DWARF debug format.
    Note: When TPF_GDWARF_LEVEL := 2 is specified, the -gdwarf-2 option is added to both the CFLAGS_ and CXXFLAGS_ settings.
  • The TKDBG variable is defined to group some _USER variables that define how an assembly, compile, or link will run. If you initialize this variable by coding TKDBG := true in the TARGET ENVIRONMENT VARIABLES section of the project configuration file, the TKDBG variable will be displayed in the Target Environment Variables area of the MakeTPF Configuration Editor for your users to specify.