Chapter 9 Generating Code and Building an Application

This chapter describes the Code Generator and its use to generate code, add user code to generated code, make the application, and run the compiled application. See "Code Generator Window" for an illustration of the Code Generator window and descriptions of its elements.

• "Making and Running an Application"

• "To Set Code Generator Options"

• "To Set Environment Options"

• "To Generate Code From the Command Line"

• "Adding User Code to Generated Code"

Making and Running an Application

Two scenarios are described below. In the first scenario, you build and run an application in one step. In the second scenario, you generate code, compile the code, and run the application in separate steps.

In either case, if you have made changes to the project that have not been saved, a message dialog box will be displayed, telling you that you have unsaved edits and giving you the choice of cancelling the generate code process or saving the project. If you choose to save the project, you will have to specify where to save the project if it has not been saved before.

To Make and Run in One Step

1. Choose Code Generator from the File menu of the App Builder primary window.

   The Code Generator is displayed.

2. Click Make & Run to generate code, build the application, and run it.

   If you have saved the project and all goes well, a number of messages will be displayed in the output pane at the top of the Code Generator. The final message will be "Running: ./[projectname]" and the application will run.

   At the least, the application primary window will be displayed. Any windows whose visibility is not set to yes at application startup will be hidden. Depending on what functionality you included that does not require user code, the application might do a variety of things. Menus can be displayed, some connections can be tested, On Item help can be displayed, and so on.

   ---

   Note -

   Ultimately, you must write some code to complete the application. For example, any Call Function callbacks specified in the Connections Editor will have to be substituted for. See "Adding User Code to Generated Code" for more information.

   ---

To Generate Code, Make, and Run Separately

1. Click Generate Code to generate code for the current project.

   As the code generator runs, messages are displayed in the output pane at the top of the Code Generator window. The final message should be "Completed successfully." A number of files will be created, including Makefiles, project files, module files, and two dtb_utils files. You can look at the files in the term pane at the bottom of the Code Generator window.

2. Click Make to build the application.

   More messages will be displayed in the Output Pane as the application is compiled. The final message again should be "Completed successfully." A few more files will be created, including object files and the executable application file, which has the name you gave the project.

3. Click Run to run the application.

   The application will be started--as if you had typed the name of the executable at the command line.

4. Click Abort to quit the application.

   This will terminate the application, closing all windows. You can also click Abort to terminate code generation or make operations started in the Code Generator window.

To Set Code Generator Options

To change the options that determine what code is generated and other Code Generator functions:

1. Choose Code Generator from the File menu of the App Builder primary window to display the Code Generator window.

2. Choose Generator from the Options menu to display the Code Generator Options dialog box.

3. Select one of the Generate Code For options (Entire Project, Main Only, Specific Modules Only, Specific Modules and Main).

   If you select Specific Modules or Specific Modules and Main, the list of modules is active. Select the names of the modules you want to generate code for in the list.

4. Click Don't Merge if you do not want your hand-edited code merged with the generated code.

   ---

   Note -

   Do not select Don't Merge unless you are sure you want to destroy the user code.

   ---

5. Choose a different message reporting option if you wish.

   Choices are Report Normal Messages, Be Silent, and Be Verbose.

6. Type Make Arguments, if appropriate.

   These arguments will be included when you click Make or Make & Run.

7. Type Run Time Arguments, if appropriate.

   These arguments will be included when you click Run or Make & Run.

8. Click Reset to Defaults to set all fields to their default values.

   Default values are Generate Code For Entire Project, Merge user code with generated code, and Report Normal Messages.

9. Click OK or Apply to make the changes.

   The Options dialog box will be dismissed if you click OK.

To Set Environment Options

1. Choose Code Generator from the File menu of the App Builder primary window to display the Code Generator window.

2. Choose Environment from the Options menu to display the Environment Options dialog box.

3. Type a variable in the Variable Name text field.

   You might want to change PATH, for instance.

4. Click Get to display the current value for the variable in Variable Name.

   The value of the variable will be displayed in the Value pane.

5. Make a change to Value and click Set to change the value of the variable.

   This change is made for this App Builder session only.

6. Click Reset to reset Value to its value outside this session of App Builder.

7. Click Cancel to dismiss the dialog box.

To Generate Code From the Command Line

To generate App Builder code from the command line, run dtcodegen. Usage is described below.

Usage: dtcodegen [options] [project-file] [module-file [module-file] ...]

Code is generated for each module specified on the command line, or for all modules in the project, if no modules are specified. If no project file is specified, a project file containing the specified module(s) is searched for in the current directory.

Files with extension .bip are assumend to be BIL project files, files with .bix extension are assumed to be encapsulated BIL files, and files with a .bil extension are assumed to be BIL module files.

Options (* = default, + = default with no project file)

-help (-h)

Print out this help message

-main

Write file containing main()

-changed

Only generate files that have changed

* -merge

Merge generated _stubs.c files with previous version

-nomerge

Don't merge existing and new stubs file

* -project (-p)

Specify a project to generate code for

-noproject (-np)

Use default project settings, ignore project file

+ -showall

Application shows (maps) all windows at startup

* -noshowall

Application shows (maps) only initially-visible windows

-silent (-s)

Silent mode, no messages written

-verbose (-v)

Verbose mode, detailed progress messages

Adding User Code to Generated Code

When you generate code for the interface you have developed by clicking Generate Code in the Code Generator window or running dtcodegen from the command line, a number of files are generated in the project folder. If your project is called "test" and it has one module, called "mod1," for instance, the following files will be created:

• Makefile (plus Makefiles for other platforms)

• dtb_utils.c

• dtb_utils.h

• mod1.bil (module file)

• mod1_stubs.c

• mod1_ui.c

• mod1_ui.h

• test.bip (project file)

• test.c

• test.h

• Test (resource file)

If you have made Call Function or Execute Code connections in the Connections Editor, those connections will show up in the generated code. All of the areas of the generated code that my be modified by you are marked with comments of the form:

/* DTB_USER_CODE_START */      

/* DTB_USER_CODE_END */

The area between the START and END comments are considered a "user segment." Any text (even non-C code) may be added within a user segment, and the code generator will preserve this code in all future versions of the code. Each user segment begins with a comment that suggests what type of code should be added in that segment, or what state the application is in when that segment is executed. These suggestions are purely informational, and may be ignored.

Neither App Builder nor the code generator verify that the code added by you is legal C code. It is your responsibility to ensure that any file you modify can be processed satisfactorily by your compiler.

If you wish to destroy all of the hand-edited code, you must either explicitly select Don't Merge from the Options dialog of the Code Generator Window, or run dtcodegen with the -nomerge option. This should be done only with great caution, as large amounts of work may be lost.

Under no circumstances should the generated comments be modified. If they are modified, code generation will fail, and the resulting file will very likely be uncompilable. A backup file, with the extension .BAK, is preserved in the current directory to help recover from such mistakes.

The user code segments appear in strategic places in the code, to allow you a great deal of freedom in customizing the generated application. All code related to main() and application-wide data and structures are defined in <projectname>.h and <projectname>.c. In these files, fields may be added to the Xt resource data structure for the application, new developer-defined data types and variables may be added, and the application's startup procedures may be amended.

Each <modulename>_stubs.c file contains user segments for modifying the effects of generated connections. Your code may be added both before and after the automatically-generated code is executed.

In addition, each file contains a user segment at the top of each file that can be used to add a custom header or copyright notice.