dtcodegen(1)

Name
dtcodegen - generate code from a Cde Application Builder project or module file

SYNOPSIS
dtcodegen [-s|-silent] [-v|-verbose] [-p|-project] [-np|-noproject] [-nomerge] [-merge] [-help] [-main] [-showall] [-changed] [filename]

DESCRIPTION
The utility reads Builder Interface Language (BIL) files created by the Cde Application Builder, a user interface and application development tool, and produces C, Motif and Cde source code for the user interface and application elements defined. The BIL files supplied can be individual module files (*.bil) or a project file (*.bip) that contains references to one or more module files.

OPTIONS

-s [-silent]
    Instructs to work silently, producing no output except error messages while generating source code.

-v [-verbose]
    Instructs to be more verbose in providing progress and status messages during the generation of source code.

-p [-project] myproj
    Specifies that dtcodegen should generate code for the project myproj, (which is expected to be defined in the file myproj.bip.

-merge
    Instructs to merge generated stubs files with previous versions, perpetuating changes made or custom edits done to the previous stubs file. By default dtcodegen performs as if this option had been specified.

-nomerge
    Prohibits dtcodegen from merging existing and new _stubs.c files. Using this option overrides the default merging behavior.

-help
    Print out a help message explaining all dtcodegen options.

-main
    Instructs to only produce the project files associated with the application's main routine.

-changed
    Instructs to only generate source code for those modules that have changed since the last time it was run.

-noproject
    Will cause the project.bip project file to be ignored and default project settings to be used instead. This is useful in producing an application from one or a few module files (e.g., for testing) as an alternative to generating the entire project.

-showall
    Indicates that the generated application should show (map) all application windows (e.g. main windows and dialogs) at startup, ignoring whether they are set to be initially visibile or not. If no project is specified on the command line will perform as if this option had been specified. (In such cases it can be turned off by using the -noshowall option).

-noshowall
    Indicates that the generated application should show at startup (map) only those windows (e.g. main windows and dialogs) whose initially-visible attribute is true. If a project is specified on the command line either by using the -project option or by specifying a project.bip file as an operand, will perform as if this option had been specified. (In such cases it can be turned off by using the -showall option).

OPERANDS
The utility accepts one or more filename operands as a way of specifying which project and modules should be processed. It is not necessary to specify the .bip or .bil extension for any file, as 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 filename operands are given, searches the current directory for a project file (*.bip). If one is found, it will be used as if it had been specified on the command line. If more than one is found, the first one encountered will be used.

If one or more filename operands are specified, checks to see if any of them are project files in the current working directory, and will use it. If none of the filename 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 filename operands provided on the command line.

Filename 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 may be used.

RESOURCES
None. The utility is not a X windows application, neither requires nor establishes a connection to an X server, and therefore has no associated X Window System Resources.

STDIN
Not used.

INPUT FILES
Files processed by the utility are required to be in the BIL format defined for the Cde Application Builder.

ENVIRONMENT VARIABLES
None.

ASYNCHRONOUS EVENTS
The utility takes the standard action for all signals.

STDOUT
Not used.

STDERR
Used only for diagnostic messages.

OUTPUT FILES
The 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
    Contains declarations and C externs for module modname.

modname_stubs.c
    Contains callback functions for the element handlers specific to module modname. Additional application code should be added to this file, as its contents are merged across runs of dtcodegen.

project.c
    If is generating code for a project, this file will contain the main() plus any callback functions that are common across modules.

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

.dtcodegen.log
    This file is produced by the utility as a record of per-module code generation and the date/time of each module 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.

EXTENDED DESCRIPTION
None.

EXIT STATUS
The following exit values are returned: Normal termination. Abnormal termination. The utility was given invalid command line options, detected an error in the format or content of the input file, failed to generate output, was only asked to generate its usage message, or determined that it was not necessary to generate any output given the timestamps on the input file and the associated files in the target directories.

CONSEQUENCES OF ERRORS
Because code generation involves the sequential production of a set of application files, errors that cause the utility to prematurely exit might also 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 may not succeed.

APPLICATION USAGE
Typically the utility is used indirectly through the Cde 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 that makes it easy to generate code, build the resulting application and then excute it.

In some cases, however, it may be desirable to use the 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

dtcodegen -p myproject
    This runs the code generator on the application defined by the project file myproject.bip.

dtcodegen myproject.bip modulename
    Runs the code generator for the project myproject.bip but only generates code for the module modulename.bil.

dtcodegen -silent mymodule
    The utility will search the current working directory for a project file that references the module mymodule and then silently generate code for just that module.

dtcodegen name1 name2
    If the project file name1.bip exists, it is used and code will be 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.

dtcodegen
    This runs the code generator, which will search the current working directory for a project file to be processed, and will generate all code associated with that project.

dtcodegen -main -p myproject
    This command will generate just the files associated with the main routine for the project myproject, namely myproject.c and myproject.h.

dtcodegen -changed
    This command searches the current working directory for a project file and, if one is found, generates code for only those modules that have changed since the code generator was last run.

dtcodegen -changed -p myproject module1 module2 module3
    This command will generate, for 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.

SEE ALSO