292 lines
17 KiB
Plaintext
292 lines
17 KiB
Plaintext
<!-- $XConsortium: ch09.sgm /main/7 1996/09/08 19:49:04 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<chapter id="ABUG.codeg.div.1">
|
|
<title id="ABUG.codeg.mkr.1">Generating Code and Building an Application</title>
|
|
<para>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 <!--Original XRef content: '&xd2;Code Generator Window&xd3;
|
|
on page 130'--><xref role="SecTitleAndPageNum" linkend="ABUG.apWDB.mkr.9">
|
|
for an illustration of the Code Generator window and descriptions of its
|
|
elements.</para>
|
|
<informaltable id="ABUG.codeg.itbl.1" frame="All">
|
|
<tgroup cols="1">
|
|
<colspec colname="1" colwidth="4.0 in">
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Making and Running an Application107'--><xref
|
|
role="JumpText" linkend="ABUG.codeg.mkr.2"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Set Code Generator Options109'--><xref
|
|
role="JumpText" linkend="ABUG.codeg.mkr.3"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Set Environment Options110'--><xref
|
|
role="JumpText" linkend="ABUG.codeg.mkr.4"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Adding User Code to Generated Code112'--><xref
|
|
role="JumpText" linkend="ABUG.codeg.mkr.6"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Generate Code from the Command
|
|
Line111'--><xref role="JumpText" linkend="ABUG.codeg.mkr.5"></para></entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
<sect1 id="ABUG.codeg.div.2">
|
|
<title id="ABUG.codeg.mkr.2">Making and Running an Application</title>
|
|
<para>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.</para>
|
|
<para>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.
|
|
</para>
|
|
<sect2 id="ABUG.codeg.div.3" role="Procedure">
|
|
<title>To Make and Run in One Step</title>
|
|
<orderedlist><listitem><para><indexterm><primary>application</primary><secondary>building and running in one step</secondary></indexterm><indexterm><primary>running application</primary><secondary>in one step</secondary></indexterm>Choose
|
|
Code Generator from the File menu of the App Builder primary window.</para>
|
|
<para>The Code Generator is displayed.<indexterm><primary>Code Generator</primary></indexterm></para>
|
|
</listitem>
|
|
<listitem><para>Click Make & Run to generate code, build the
|
|
application, and run it.</para>
|
|
<para>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: ./[<emphasis>projectname</emphasis>]”
|
|
and the application will run.</para>
|
|
<para>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.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<note>
|
|
<para>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 <!--Original XRef content: '&xd2;Adding
|
|
User Code to Generated Code&xd3; on
|
|
page 112'--><xref role="SecTitleAndPageNum" linkend="ABUG.codeg.mkr.6">
|
|
for more information.</para>
|
|
</note>
|
|
</sect2>
|
|
<sect2 id="ABUG.codeg.div.4" role="Procedure">
|
|
<title>To Generate Code, Make, and Run Separately</title>
|
|
<orderedlist><listitem><para>Click Generate Code to generate code for the
|
|
current project.<indexterm><primary>application</primary><secondary>generating
|
|
code for</secondary></indexterm><indexterm><primary>generating code for application</primary></indexterm></para>
|
|
<para>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 <filename>dtb_utils</filename> files.
|
|
You can look at the files in the term pane at the bottom of the Code Generator
|
|
window.</para>
|
|
</listitem><listitem><para>Click Make to build the application.<indexterm>
|
|
<primary>application</primary><secondary>building</secondary></indexterm><indexterm>
|
|
<primary>building application</primary></indexterm></para>
|
|
<para>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.</para>
|
|
</listitem><listitem><para>Click Run to run the application.<indexterm>
|
|
<primary>application</primary><secondary>running</secondary></indexterm><indexterm>
|
|
<primary>running application</primary></indexterm></para>
|
|
<para>The application will be started—as if you had typed the name of
|
|
the executable at the command line.</para>
|
|
</listitem><listitem><para>Click Abort to quit the application.<indexterm>
|
|
<primary>application</primary><secondary>quitting</secondary></indexterm><indexterm>
|
|
<primary>quitting</primary><secondary>application</secondary></indexterm></para>
|
|
<para>This will terminate the application, closing all windows. You can also
|
|
click Abort to terminate code generation or <command>make</command> operations
|
|
started in the Code Generator window.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
<sect2 id="ABUG.codeg.div.5" role="Procedure">
|
|
<title id="ABUG.codeg.mkr.3">To Set Code Generator Options<indexterm><primary>options, Code Generator</primary></indexterm><indexterm><primary>Code Generator</primary><secondary>options</secondary></indexterm><indexterm><primary>setting</primary><secondary>Code Generator options</secondary></indexterm></title>
|
|
<para>To change the options that determine what code is generated and other
|
|
Code Generator functions:</para>
|
|
<orderedlist><listitem><para>Choose Code Generator from the File menu of the
|
|
App Builder primary window to display the Code Generator window.</para>
|
|
</listitem><listitem><para>Choose Generator from the Options menu to display
|
|
the Code Generator Options dialog box.</para>
|
|
</listitem><listitem><para>Select one of the Generate Code For options (Entire
|
|
Project, Main Only, Specific Modules Only, Specific Modules and Main).</para>
|
|
<para>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.</para>
|
|
</listitem><listitem><para>Click Don't Merge if you do not want your hand-edited
|
|
code merged with the generated code.</para>
|
|
<note>
|
|
<para>Do not select Don't Merge unless you are sure you want to destroy the
|
|
user code.</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem><para>Choose a different message reporting option if
|
|
you wish.</para>
|
|
<para>Choices are Report Normal Messages, Be Silent, and Be Verbose.</para>
|
|
</listitem><listitem><para>Type Make Arguments, if appropriate.</para>
|
|
<para>These arguments will be included when you click Make or Make & Run.
|
|
</para>
|
|
</listitem><listitem><para>Type Run Time Arguments, if appropriate.</para>
|
|
<para>These arguments will be included when you click Run or Make & Run.
|
|
</para>
|
|
</listitem><listitem><para>Click Reset to Defaults to set all fields to their
|
|
default values.</para>
|
|
<para>Default values are Generate Code For Entire Project, Merge user code
|
|
with generated code, and Report Normal Messages.</para>
|
|
</listitem><listitem><para>Click OK or Apply to make the changes.</para>
|
|
<para>The Options dialog box will be dismissed if you click OK.</para>
|
|
</listitem></orderedlist>
|
|
</sect2>
|
|
<sect2 id="ABUG.codeg.div.6" role="Procedure">
|
|
<title id="ABUG.codeg.mkr.4">To Set Environment Options<indexterm><primary>environment options, Code Generator</primary></indexterm><indexterm><primary>setting</primary><secondary>environment options</secondary></indexterm></title>
|
|
<orderedlist><listitem><para>Choose Code Generator from the File menu of the
|
|
App Builder primary window to display the Code Generator window.</para>
|
|
</listitem><listitem><para>Choose Environment from the Options menu to display
|
|
the Environment Options dialog box.</para>
|
|
</listitem><listitem><para>Type a variable in the Variable Name text field.
|
|
</para>
|
|
<para>You might want to change <command>PATH</command>, for instance.</para>
|
|
</listitem><listitem><para>Click Get to display the current value for the
|
|
variable in Variable Name.</para>
|
|
<para>The value of the variable will be displayed in the Value pane.</para>
|
|
</listitem><listitem><para>Make a change to Value and click Set to change
|
|
the value of the variable.</para>
|
|
<para>This change is made for this App Builder session only.</para>
|
|
</listitem><listitem><para>Click Reset to reset Value to its value outside
|
|
this session of App Builder.</para>
|
|
</listitem><listitem><para>Click Cancel to dismiss the dialog box.</para>
|
|
</listitem></orderedlist>
|
|
</sect2>
|
|
<sect2 id="ABUG.codeg.div.7" role="Procedure">
|
|
<title id="ABUG.codeg.mkr.5">To Generate Code from the Command Line</title>
|
|
<para>To generate App Builder code from the command line, run <command>dtcodegen</command>. Usage is described below.</para>
|
|
<para>Usage: <command>dtcodegen</command> [<symbol role="Variable">options</symbol>] [<symbol role="Variable">project-file</symbol>] [ <symbol role="Variable">module-file</symbol> [<symbol role="Variable">module-file</symbol>] ...]</para>
|
|
<para>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.</para>
|
|
<para>Files with extension <filename>.bip</filename> are assumend to be BIL
|
|
project files, files with <filename>.bix</filename> extension are assumed
|
|
to be encapsulated BIL files, and files with a <filename>.bil</filename>
|
|
extension are assumed to be BIL module files.</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec align="left" colname="col1" colwidth="169*">
|
|
<colspec align="left" colname="col2" colwidth="359*">
|
|
<spanspec nameend="col2" namest="col1" spanname="1to2">
|
|
<thead>
|
|
<row><entry align="left" spanname="1to2" valign="bottom"><para>Options (* = default, + = default with no project
|
|
file)</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><para><command>-help (-h)</command></para></entry>
|
|
<entry><para>Print out this help message</para></entry></row>
|
|
<row>
|
|
<entry><para><filename>-main</filename></para></entry>
|
|
<entry><para>Write file containing main()</para></entry></row>
|
|
<row>
|
|
<entry><para><filename>-changed</filename></para></entry>
|
|
<entry><para>Only generate files that have changed</para></entry></row>
|
|
<row>
|
|
<entry><para><command>* -merge</command></para></entry>
|
|
<entry><para>Merge generated _stubs.c files with previous version</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><filename>-nomerge</filename></para></entry>
|
|
<entry><para>Don't merge existing and new stubs file</para></entry></row>
|
|
<row>
|
|
<entry><para><command>* -project (-p)</command></para></entry>
|
|
<entry><para>Specify a project to generate code for</para></entry></row>
|
|
<row>
|
|
<entry><para><command>-noproject (-np)</command></para></entry>
|
|
<entry><para>Use default project settings, ignore project file</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><command>+ -showall</command></para></entry>
|
|
<entry><para>Application shows (maps) all windows at startup</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><command>* -noshowall</command></para></entry>
|
|
<entry><para>Application shows (maps) only initially-visible windows
|
|
</para></entry></row>
|
|
<row>
|
|
<entry><para><command>-silent (-s)</command></para></entry>
|
|
<entry><para>Silent mode, no messages written</para></entry></row>
|
|
<row>
|
|
<entry><para><command>-verbose (-v)</command></para></entry>
|
|
<entry><para>Verbose mode, detailed progress messages</para></entry></row>
|
|
</tbody></tgroup></informaltable>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="ABUG.codeg.div.8">
|
|
<title id="ABUG.codeg.mkr.6">Adding User Code to Generated Code</title>
|
|
<para>When you generate code for the interface you have developed by clicking
|
|
Generate Code in the Code Generator window or running <command>dtcodegen</command> 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:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><command>Makefile</command>
|
|
(plus Makefiles for other platforms)</para>
|
|
</listitem><listitem><para><filename>dtb_utils.c</filename></para>
|
|
</listitem><listitem><para><filename>dtb_utils.h</filename></para>
|
|
</listitem><listitem><para><filename>mod1.bil</filename> (module file)</para>
|
|
</listitem><listitem><para><filename>mod1_stubs.c</filename></para>
|
|
</listitem><listitem><para><filename>mod1_ui.c</filename></para>
|
|
</listitem><listitem><para><filename>mod1_ui.h</filename></para>
|
|
</listitem><listitem><para><filename>test.bip</filename> (project file)</para>
|
|
</listitem><listitem><para><filename>test.c</filename></para>
|
|
</listitem><listitem><para><filename>test.h</filename></para>
|
|
</listitem><listitem><para><command>Test</command> (resource file)</para>
|
|
</listitem></itemizedlist>
|
|
<para>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:</para>
|
|
<programlisting>/* DTB_USER_CODE START */
|
|
/* DTB_USER_CODE_END */
|
|
</programlisting>
|
|
<para>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.</para>
|
|
<para>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.</para>
|
|
<para>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 <command>dtcodegen</command> with the <filename>-nomerge</filename>
|
|
option. This should be done only with great caution, as large amounts of
|
|
work may be lost.</para>
|
|
<para>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 <filename>.BAK</filename>, is preserved in the current directory to help recover from
|
|
such mistakes.</para>
|
|
<para>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 <filename>main()</filename> and application-wide data and
|
|
structures are defined in <<emphasis>projectname</emphasis>><filename>.h</filename> and <<emphasis>projectname</emphasis>><filename>.c</filename>.
|
|
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.</para>
|
|
<para>Each <<emphasis>modulename</emphasis>><filename>_stubs.c</filename>
|
|
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.</para>
|
|
<para>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.</para>
|
|
</sect1>
|
|
</chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:11:44-->
|
|
<?Pub *0000022158>
|