"dtcodegen"("user) manual page

Name

dtcodegen -- generate code from a XCDE application building services project or module file

dtcodegen [-help]

Description

The dtcodegen utility reads Builder Interface Language (BIL) files created by the XCDE application building services graphical user interface and produces C, Motif and XCDE source code for the user interface and application elements defined. The BIL files supplied can be individual module files (files with a .bil suffix) or a project file (files with a .bip suffix) that contains references to zero or more module files.

Options

The following options are available:

-changed: Generate only source code for those modules that have changed since the last time dtcodegen was run.
-help: Write a help message to standard output explaining all dtcodegen options and then terminate.
-main: Produce the project files associated with the application’s main routine.
-merge: Merge generated stubs files with previous versions, perpetuating changes made or custom edits done to the previous stubs file. This is the default behavior.
-nomerge: Do not merge existing and new _stubs.c files. This option overrides the default merging behavior. If both -merge and -nomerge are used, the one given last on the command line takes precedence.
-module mymod: Generate code for the module mymod, (which is expected to be defined in the file mymod .bil). Using multiple -module options includes multiple modules in the generated code.
-useWC class: Use the specified widget class whenever possible. Valid values are:
dt: Generate DtComboBox and DtSpinBox widgets. This value retains the CDE 1.0 behavior.
xm: Generate XmComboBox and XmSimpleSpinBox widgets. This value selects the Motif/Xm behavior.

-p!|!-project myproj: Generate code for the project myproj, (which is expected to be defined in the file myproj .bip).
-noproject: Ignore the project.bip project file and use default project settings instead. This is useful in producing an application from one or a few module files (for example, for testing) as an alternative to generating the entire project.
-showall: Cause the generated application to show (map) all application windows (main windows and dialogs) at startup, ignoring whether they are set to be initially visible or not. If no project is specified on the command line, either by using -project or by specifying a project .bip file as an operand, dtcodegen performs as if -showall had been specified. (The -noshowall option suppresses this behavior).
-noshowall: Cause the generated application to show at startup (map) only those windows (main windows and dialogs) whose initially visible attribute is true. If a project is specified on the command line, either by using -project or by specifying a project .bip file as an operand, dtcodegen performs as if -noshowall had been specified. (The -showall option suppresses this behavior).
-s!|!-silent: Work silently, producing no output except error messages while generating source code.
-v!|!-verbose: Be more verbose in providing progress and status messages during the generation of source code.

Operands

The following operand is supported:

file: A pathname of a project or module file. It is not necessary to specify the .bip or .bil extension for any file because dtcodegen uses a sequence of search algorithms in the current directory to determine what files should be read in order to satisfy the specified command line.
If no: file operands are given, dtcodegen searches the current directory for a project file (a file with a .bip suffix). If one is found, it is used as if it had been specified on the command line. If more than one is found, the first one encountered is used.
If one or more file: operands are specified, dtcodegen checks to see if any of them is a project file in the current working directory, and uses the first one found. If none of the file operands are project files, then the directory is searched for a project file. This search is similar to the no-operand case, but is modified to look for a project file that contain modules corresponding to other file operands.
Operands other than the project file are: taken to be module names.

See the EXAMPLES section for more on the interpretation of filename operands and how the search features of dtcodegen may be used.

Resources

If the -useWC option is not specified, dtcodegen uses the useWidgetClass resource in the Xt resources table to determine which class to use for generated widgets. The class/type is XmCUseWidgetClass/XtEnum and the valid values are:

xm (the default): Generate XmComboBox and XmSimpleSpinBox widgets. This value selects the Motif/Xm behavior.
dt: Generate DtComboBox and DtSpinBox widgets. This value retains the CDE 1.0 behavior.

Stdin

Not used.

Input Files

All input files are text files in the BIL format. See BIL(4) .

Environment Variables

The following environment variables affect the execution of dtcodegen:

LANG: Provide a default value for the internationalization variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility behaves as if none of the variables had been defined.
LC_ALL: If set to a non-empty string value, override the values of all the other internationalization variables.
LC_MESSAGES: Determine the locale that is used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output.
NLSPATH: Determine the location of message catalogues for the processing of LC_MESSAGES.

Asynchronous Events

The dtcodegen utility takes the standard action for all signals.

Stdout

When -help is specified, dtcodegen writes to standard output a usage message in an unspecified format. Otherwise, standard output is not used.

Stderr

When -verbose is specified, dtcodegen writes to standard error informational progress messages and diagnostic messages in an unspecified format. Otherwise, standard error is used only for diagnostic messages.

Output Files

The dtcodegen utility produces the following files:

modname_ui.c

The primary source code file for module modname, containing C code to create the objects in the module and establish connections for those objects.

modname_ui.h

Declarations and C externs for module modname.

modname_stubs.c

Callback functions for the element handlers specific to module modname.

project.c

If dtcodegen is generating code for a project, this file contains main plus any callback functions that are common across modules.

project.h

If dtcodegen is generating code for a project, this file contains declarations for any callback functions and C externs that are common across interfaces. ..

A record of per-module code generation and the date and time of each module as it was processed. This data is required to provide support for the -changed option as part of determining which files need to be regenerated and which ones do not.

Additional application code should be added to the modname _stubs.c, project .c and project .c files, as appropriate, because their contents are merged across runs of dtcodegen.

Extended Description

None.

Exit Status

The following exit values are returned:

0: successful completion
>0: an error occurred

Consequences of Errors

Because code generation involves the sequential production of a set of application files, errors that cause the dtcodegen utility to exit prematurely also may result in some module or project source files having been generated while others were not. Attempts to build the application from this mix of new and old generated code produce undefined results.

Application Usage

Typically the dtcodegen utility is used indirectly through the XCDE Application Builder’s Code Generator dialog. This allows application code to be generated while the user is working with the Application Builder rather than through a separate interface or shell command line. The Code Generator dialog provides a graphical user interface for dtcodegen that makes it easy to generate code, build the resulting application and then execute it.

In some cases, however, it may be desirable to use the dtcodegen utility directly. A common example of this usage is to employ the code generator from within an application Makefile to produce a portion of the application code from pre-existing project or module files.

Examples

Run the code generator on the application defined by the project file myproject.bip:

CWdtcodegen -p myproject

Run the code generator for the project myproject.bip, but only generate code for the module modulename.bil:

CWdtcodegen myproject.bip modulename

Search the current working directory for a project file that references the module mymodule and then silently generate code for just that module:

CWdtcodegen -silent mymodule

In the following example:

CWdtcodegen name1 name2

if the project file name1.bip exists, it is used and code is generated for module name2.bil. Otherwise, both name1 and name2 are taken as the name of modules, the current working directory is searched for a project file that references both modules, and code for those two modules is generated.

Run the code generator, which searches the current working directory for a project file to be processed, and generates all code associated with that project:

CWdtcodegen

Generate just the files associated with the main routine for the project myproject, namely myproject.c and myproject.h:

CWdtcodegen -main -p myproject

Search the current working directory for a project file and, if one is found, generate code for only those modules that have changed since the code generator was last run:

CWdtcodegen -changed

Generate, for the project myproject.bip, code only for those modules among the set module1, module2 and module3 that have changed since the last time the code generator was run:

CWdtcodegen -changed -p myproject module1 module2 module3