diff options
| author | Kevin Koch <kpkoch@mit.edu> | 2007-03-27 18:42:51 +0000 |
|---|---|---|
| committer | Kevin Koch <kpkoch@mit.edu> | 2007-03-27 18:42:51 +0000 |
| commit | fb48afbb637e35becf463e26399f9ad90cc74e7d (patch) | |
| tree | 8e115c5baed0ea0699a0a87d76bf6a010cdda082 | |
| parent | cbcc29c1892ba744d67471a9b386077fac18c50f (diff) | |
| download | krb5-fb48afbb637e35becf463e26399f9ad90cc74e7d.tar.gz krb5-fb48afbb637e35becf463e26399f9ad90cc74e7d.tar.xz krb5-fb48afbb637e35becf463e26399f9ad90cc74e7d.zip | |
Update documentation
Target_Version: 1.6.1
Ticket: 5490
Tags: pullup
git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@19294 dc483132-0cff-0310-8789-dd5450dbe970
| -rw-r--r-- | src/windows/build/bkw-automation.html | 486 |
1 files changed, 277 insertions, 209 deletions
diff --git a/src/windows/build/bkw-automation.html b/src/windows/build/bkw-automation.html index f018b348bd..eb41053c5b 100644 --- a/src/windows/build/bkw-automation.html +++ b/src/windows/build/bkw-automation.html @@ -10,218 +10,286 @@ <LINK href="css\main-action(1).css" type="text/css" rel="stylesheet">
<META content="MSHTML 6.00.2900.3059" name="GENERATOR"></HEAD>
<BODY>
- <DIV id="PageContent">
- <TABLE style="MARGIN-TOP: 0px" cellSpacing="0" cellPadding="0" width="100%">
- <TBODY>
+ <DIV style="MARGIN-LEFT: 10px; MARGIN-RIGHT: 10px" align="left">
+ <DIV class="wiki-content" style="MARGIN-TOP: 5px; MARGIN-BOTTOM: 5px" align="left">The
+ Kerberos For Windows build is being automated. This description consists of
+ </DIV>
+ <UL>
+ <LI>
+ <A href="#lore-bkw-automation-Buildsteps">Build steps</A>
+ <LI>
+ <A href="#Script-structure">Script structure</A>
+ <LI>
+ <A href="#Configfile">Config file</A>
+ <LI>
+ <A href="#Remainingwork">Remaining work / bug list</A>
+ <LI>
+ <A href="#Troubleshooting">Troubleshooting</A></LI>
+ </UL>
+ <H2><A name="lore-bkw-automation-Buildsteps"></A>Build steps</H2>
+ <P>Building the complete KfW product consists of these steps:</P>
+ <UL>
+ <LI>
+ Setting up the environment
+ <LI>
+ Fetching sources from repositories
+ <LI>
+ Building the sources with nmake
+ <LI>
+ Setting up the packaging environment
+ <LI>
+ Building the two installers -- a msi installer and an exe installer
+ <LI>
+ Building other distribution components
+ <UL>
+ <LI>
+ KfW source distribution
+ <LI>
+ KfW core binaries
+ <LI>
+ KfW SDK
+ <LI>
+ Microsoft redistributable components
+ <LI>
+ Individual files: release notes, Leash user guide, MSI Deployment Guide.
+ </LI>
+ </UL>
+ </LI>
+ </UL>
+ <H2><A name="Script-structure"></A>Script structure</H2>
+ <P>The build is a perl script controlled by command line switches and an XML
+ configuration file. The config file is required. Settings in the config file
+ can be overridden by optional command line switches.</P>
+ <P>The main steps in the script are</P>
+ <UL>
+ <LI>
+ Setting up the environment
+ <LI>
+ Fetching the sources from repositories
+ <LI>
+ Building the sources
+ <LI>
+ Setting up the packaging environment
+ <LI>
+ Building the msi with the package nmake
+ <LI>
+ Building the rest of the components
+ </LI>
+ </UL>
+ <P>The usage message shows the available switches:</P>
+ <P><TT>C:\Projects\KfW>perl bkw.pl /?</TT><BR>
+ <TT>Usage: bkw.pl (-f --config) config-file [options] NMAKE-options</TT></P>
+ <P><TT>Options are case insensitive.</TT></P>
+ <P><TT>Options:</TT><BR>
+ <TT>/help /? usage information (what you now see)</TT><BR>
+ <TT>/srcdir dir Source directory to use. Should contain</TT><BR>
+ <TT>
+ pismere/athena. If cvstag or svntag is null,</TT><BR>
+ <TT>
+ the directory should be prepopulated.</TT><BR>
+ <TT>/cvstag tag \ For whichever of these tags is specified,</TT><BR>
+ <TT>/svntag url / a checkout will be done into srcdir</TT><BR>
+ <TT>/debug Do debug make instead of
+ release make</TT><BR>
+ <TT>/outdir dir Directory to be created where build results will go</TT><BR>
+ <TT>/nomake Skip make step</TT><BR>
+ <TT>/nopackage Skip packaging step</TT><BR>
+ <TT>/clean Build clean target</TT><BR>
+ <TT>/verbose Debug mode - verbose output</TT><BR>
+ <TT>/vverbose very verbose output</TT><BR>
+ <TT>/config path Path to config file</TT><BR>
+ <TT>/logfile path Where to write output. If omitted, ...</TT><BR>
+ <TT>/srcdir dir Source directory to use. Should contain
+ <BR>
+ </TT><TT>pismere/athena.
+ If cvstag or svntag is null,
+ <BR>
+
+ the directory should be prepopulated.
+ <BR>
+ </TT><TT>/outdir dir Directory to be created where build results will
+ go
+ <BR>
+ /repository checkout | co \ What repository action to take.
+ <BR>
+ </TT><TT>update
+ | up | Options are to checkout, update or<BR>
+ skip
+ / take no action [skip].
+ <BR>
+ /cvstag tag \ For whichever of these tags is specified,
+ <BR>
+ </TT><TT>/svntag url / the repository action will be done into srcdir
+ <BR>
+ /debug Do debug make instead of
+ release make
+ <BR>
+ /nomake Skip make step
+ <BR>
+ /nopackage Skip packaging step
+ <BR>
+ /clean Build clean target
+ <BR>
+ /verbose Debug mode - verbose output
+ <BR>
+ /config path Path to config file
+ <BR>
+ /logfile path Where to write output. If omitted, ...<BR>
+ </TT><TT>Other:</TT><BR>
+ <TT>NMAKE-options any options you want to pass to NMAKE, which can be:</TT><BR>
+ <TT>(note: /nologo is always used)</TT><BR>
+ <TT>[ nmake options follow ]</TT></P>
+ <P>Additional controls, not available from the command line:</P>
+ <P><TT><CVSROOT name=":kserver:cvs.mit.edu:/cvs/pismere" /></TT><BR>
+ <TT><SVNURL name="" /></TT><BR>
+ <TT><CopyList><Config><DebugArea value="dbg" /></TT><BR>
+ <TT>
+ <ReleaseArea value="rel" /></TT><BR>
+ <TT> <AlwaysTag
+ value="%bldtype%" /></TT><BR>
+ <TT>
+ <DebugTag value="%debug%" /></TT><BR>
+ <TT>
+ <ReleaseTag value="%release%" /></TT><BR>
+ <TT>
+ <Files><Include path="copyfiles.xml" /></TT></P>
+ <P><TT><FONT face="Verdana">The pre-package steps gathers up build results and puts them in
+ a <FONT face="Courier">target</FONT> area. "target" is hardwired in the
+ build script.</FONT></TT></P>
+ <P><TT><FONT face="Verdana">The post-package step zips up various files and then copies the
+ zips and other files to<FONT face="Courier"><EM>srcdir</EM></FONT>/<FONT face="Courier">public</FONT>.
+ "public" is hardwired in the build script.</FONT></TT></P>
+ <H2><A name="#Configfile"></A>Config file</H2>
+ <H3>
+ CopyLists</H3>
+ <P>
+ CopyLists are used in many places. There is an optional
+ Configuration section and a required Files section. </P>
+ <P>The configuration section defines the roots of the from and to paths and can
+ optionally define path substitutions.
+ </P>
+ <P>Internally, the to and from paths are required. They are forced by the
+ script rather than being set in the config file. Comments in the copyfile
+ xml indicate this.</P>
+ <P>The overall build configuration specifies a debug or release build. The
+ debug and release results are put in different places. File entries can
+ indicate a variable part of a path with a tag such as %bldtype%. The
+ script will substitute %bldtype% with either dbg or rel, depending on the build
+ type. The substitution tags are specified with these declarations:</P>
+ <P>
+ <TABLE id="Table1" height="0" cellSpacing="1" cellPadding="1" border="1">
<TR>
- <TD vAlign="top" width="100%"><!-- Inner content table -->
- <TABLE cellSpacing="0" cellPadding="2" width="100%">
- <TBODY>
- <TR>
- <TD vAlign="top" width="100%">
- <DIV style="MARGIN-BOTTOM: 10px; MARGIN-LEFT: 10px">
- <DIV class="wiki-content" style="MARGIN-TOP: 5px; MARGIN-BOTTOM: 5px">The Kerberos
- For Windows build is being automated. This description consists of
- </DIV>
- </DIV>
- <DIV id="content" style="MARGIN-LEFT: 10px">
- <DIV class="wiki-content" style="MARGIN-RIGHT: 10px">
- <UL>
- <LI>
- Build steps
- <LI>
- Script structure
- <LI>
- Script step details
- <LI>
- Remaining work / bug list
- </LI>
- </UL>
- <H2><A name="lore-bkw-automation-Buildsteps"></A>Build steps</H2>
- <P>Building the complete KfW product consists of these steps:</P>
- <UL>
- <LI>
- Setting up the environment [Done except for subversion, logging]
- <LI>
- Fetching sources from repositories [cvs done; subversion being worked on]
- <LI>
- Building the sources with nmake [Done]
- <LI>
- Setting up the packaging environment [Done]
- <LI>
- Building KfW.msi with the packaging nmake [Done]
- <LI>
- Building other distribution components [Not done]
- <UL>
- <LI>
- .exe installer
- <LI>
- KfW source distribution
- <LI>
- KfW core binaries
- <LI>
- KfW SDK
- <LI>
- Microsoft redistributable components
- <LI>
- Individual files: release notes, Leash user guide, MSI Deployment Guide.
- </LI>
- </UL>
- </LI>
- </UL>
- <H2>Script structure</H2>
- <P>The build is a perl script controlled by command line switches and an XML
- configuration file. The config file is required. Settings in the config file
- can be overridden by optional command line switches.</P>
- <P>The main steps in the script are</P>
- <UL>
- <LI>
- Setting up the environment
- <LI>
- Fetching the sources from repositories
- <LI>
- Building the sources
- <LI>
- Setting up the packaging environment
- <LI>
- Building the msi with the package nmake
- <LI>
- Building the rest of the components [tbd]
- </LI>
- </UL>
- <P>The usage message shows the available switches:</P>
- <P><TT>C:\Projects\KfW>perl bkw.pl /?</TT><BR>
- <TT>Usage: bkw.pl (-f --config) config-file [options] NMAKE-options</TT></P>
- <P><TT>Options are case insensitive.</TT></P>
- <P><TT>Options:</TT><BR>
- <TT>/help /? usage information (what you now see)</TT><BR>
- <TT>/srcdir dir Source directory to use. Should contain</TT><BR>
- <TT>
- pismere/athena. If cvstag or svntag is null,</TT><BR>
- <TT>
- the directory should be prepopulated.</TT><BR>
- <TT>/cvs?ag tag \ For whichever of these tags is specified,</TT><BR>
- <TT>/svntag url / a checkout will be done into srcdir</TT><BR>
- <TT>/debug Do debug make instead of
- release make</TT><BR>
- <TT>/outdir dir Directory to be created where build results will go</TT><BR>
- <TT>/nomake Skip make step</TT><BR>
- <TT>/nopackage Skip packaging step</TT><BR>
- <TT>/clean Build clean target</TT><BR>
- <TT>/verbose Debug mode - verbose output</TT><BR>
- <TT>/vverbose very verbose output</TT><BR>
- <TT>/config path Path to config file</TT><BR>
- <TT>/logfile path Where to write output. If omitted, ...</TT><BR>
- <TT>/srcdir dir Source directory to use. Should contain
- <BR>
- </TT><TT>pismere/athena.
- If cvstag or svntag is null,
- <BR>
-
- the directory should be prepopulated.
- <BR>
- </TT><TT>/outdir dir Directory to be created where build results will
- go
- <BR>
- /repository checkout | co \ What repository action to take.
- <BR>
- </TT><TT>update
- | up | Options are to checkout, update or<BR>
- skip
- / take no action [skip].
- <BR>
- /cvstag tag \ For whichever of these tags is specified,
- <BR>
- </TT><TT>/svntag url / the repository action will be done into srcdir
- <BR>
- /debug Do debug make instead of release make
- <BR>
- /nomake Skip make step
- <BR>
- /nopackage Skip packaging step
- <BR>
- /clean Build clean target
- <BR>
- /verbose Debug mode - verbose output
- <BR>
- /config path Path to config file
- <BR>
- /logfile path Where to write output. If omitted, ...<BR>
- </TT><TT>Other:</TT><BR>
- <TT>NMAKE-options any options you want to pass to NMAKE, which can be:</TT><BR>
- <TT>(note: /nologo is always used)</TT><BR>
- <TT>[ nmake options follow ]</TT></P>
- <P>Additional controls, not available from the command line:</P>
- <P><TT><CVSROOT name=":kserver:cvs.mit.edu:/cvs/pismere" /></TT><BR>
- <TT><SVNURL name="" /></TT><BR>
- <TT><CopyList><Config><DebugArea value="dbg" /></TT><BR>
- <TT>
- <ReleaseArea value="rel" /></TT><BR>
- <TT> <AlwaysTag
- value="%bldtype%" /></TT><BR>
- <TT>
- <DebugTag value="%debug%" /></TT><BR>
- <TT>
- <ReleaseTag value="%release%" /></TT><BR>
- <TT>
- <Files><Include path="copyfiles.xml" /></TT></P>
- <H3>The CopyList</H3>
- <P>The <TT>CopyList</TT> is used during the Setting Up The Packaging Environment
- step. Build results and files from all over the source tree are copied into a
- 'staging' area in a structure the packaging script expects. The staging area is <TT>
- <src>/pismere/staging</TT>.</P>
- <P>The original copy list on which this is based had duplicate entries for debug
- and release build results. This version only names each file once, which could
- reduce maintenance.</P>
- <P>A copylist entry looks like this:</P>
- <DIV class="preformattedContent"><PRE><File name="comerr32.dll" from="..\target\bin\i386\%bldtype%\" to="\bin\i386" />
-</PRE>
- </DIV>
- <P>From paths are relative to <TT><src>\pismere\athena</TT> and To paths are
- relative to <TT><src>\pismere\staging</TT>.</P>
- <P>Debug and release build results go into directories containing either 'dbg' or
- 'rel.' <TT>DebugArea</TT> and <TT>ReleaseArea</TT> describe these strings. If
- an entry in the copy list contains the <TT>AlwaysTag</TT> string ('%bldtype%'),
- the debug or release file will be copied, depending on the build type. If the
- copy list entry contains <TT>DebugTag</TT> ('%debug%'), the file will only be
- copied if packaging a debug build. Ditto for <TT>ReleaseTag<?TT>.</P>
- <P>If we are doing a debug build, the above copylist entry will copy <TT><src>\pismere\athena\..\target\bin\i386\dbg\comerr32.dll</TT>
- to <TT><src>\pismere\staging\bin\i386\comerr32.dll</TT>.</P>
- <P>There are two other possible attributes in a copylist entry:</P>
- <UL>
- <LI>
- <TT>notrequired</TT>
- <LI>
- <TT>newname="filename"</TT>
- </LI>
- </UL>
- <P>Most copylist entries are required and the script will die if they aren't
- present. To ignore missing files, add <TT>notrequired</TT>.</P>
- <P>To rename the file, set the <TT>newname</TT> attribute.</P>
- <H2><FONT face="Verdana">Remaining work / bug list</FONT></H2>
- <P>This is a work in progress. What's left:</P>
- <UL>
- <LI>
- <FONT face="Verdana">Produce the remainder of the distribution components. [Listed
- above.] </FONT>
- </LI>
- </UL>
- <P>Bugs:</P>
- <UL>
- <LI>
- <FONT face="Verdana">Propogate leash removal through wix scripts. </FONT>
- <LI>
- <FONT face="Verdana">Eliminate need for redundant <TT>/debug debug</TT>. </FONT>
- </LI>
- </UL>
- </DIV>
- </DIV>
- </TT></TD>
- </TR>
- </TBODY></TABLE>
+ <TD>DebugArea</TD>
+ <TD height="21">Path value used in debug build. Must match what the build
+ script uses. Typically "dbg."</TD>
+ </TR>
+ <TR>
+ <TD>ReleaseArea</TD>
+ <TD height="9">Path value used in release build. Must match the build
+ script. Typically "rel."</TD>
+ </TR>
+ <TR>
+ <TD>AlwaysTag</TD>
+ <TD height="17">String in file entries which will always be changed to either
+ DebugArea or ReleaseArea. File is always copied. Typically "%bldtype%."</TD>
+ </TR>
+ <TR>
+ <TD>DebugTag</TD>
+ <TD>String in file entries which will only be changed to DebugArea during a debug
+ build. File is only copied in a debug build. Typically "%debug%."</TD>
+ </TR>
+ <TR>
+ <TD>ReleaseTag</TD>
+ <TD>String in file entries which will only be changed to ReleaseArea during a
+ release build. File is only copied in a release build. Typically
+ "%release%."</TD>
+ </TR>
+ <TR>
+ <TD>FileStem</TD>
+ <TD>%filestem% will always be changed to FileStem. Example:
+ "kfw-3-2-0." This is used in when building or copying the final build
+ results.</TD>
+ </TR>
+ </TABLE>
+ </P>
+ <P><STRONG>Example</STRONG></P>
+ <P>Each segment of the file's path that comes from a different place is in a
+ different color.</P>
+ <P>
+ Release build. Config file:
+ </P>
+ <P>
+ <TABLE id="Table2" cellSpacing="1" cellPadding="1" border="0">
+ <TR>
+ <TD colspan="4"><FONT face="courier"><BKW_Config></FONT></TD>
+ </TR>
+ <TR>
+ <TD width="23"></TD>
+ <TD colspan="3"><FONT face="courier"><CommandLine></FONT></TD>
+ </TR>
+ <TR>
+ <TD width="23"></TD>
+ <TD width="20"></TD>
+ <TD colspan="2"><FONT face="courier"><Directories></FONT></TD>
+ </TR>
+ <TR>
+ <TD width="23"></TD>
+ <TD width="20"></TD>
+ <TD width="22"></TD>
+ <TD><FONT face="courier"><src path ="<FONT color="#000099">C:\projects\Autobuild"</FONT>
+ /></FONT>
</TD>
</TR>
- </TBODY></TABLE>
+ </TABLE>
+ </P>
+ <P>Copylist comments:</P>
+ <P class="code">
+ <!-- File from paths are relative to
+ <src>\<FONT color="#ff00cc">pismere\athena</FONT> -->
+<BR>
+ <!-- File to paths are relative to <src>\<FONT color="#00ff00">pismere\staging</FONT>
+ -->
+ </P>
+ <P>When the script processes this copylist, it will force the from and to paths as
+ indicated.</P>
+ <P>This line
+ </P>
+ <P class="code"><File name="<FONT color="#00ffff">comerr32.dll</FONT>" from="<FONT color="#ff9933">..\target\bin\i386</FONT>\<FONT color="#ff0000">%bldtype%</FONT>\"
+ to="\<FONT color="#9966ff">bin\i386</FONT>" /></P>
+ <P>will result in <FONT face="Courier"><FONT color="#000099">C:\projects\Autobuild</FONT>\<FONT color="#ff00cc">pismere\athena</FONT>\<FONT color="#ff9933">..\target\bin\i386</FONT>\<FONT color="#ff0000">rel</FONT>\<FONT color="#00ffff">comerr32.dll</FONT></FONT></P>
+ <P>being copied to <FONT face="Courier"><FONT color="#000099">C:\projects\Autobuild</FONT>\<FONT color="#00ff00">pismere\staging</FONT>\<FONT color="#9966ff">bin\i386</FONT>\<FONT color="#00ffff">comerr32.dll</FONT></FONT>.</P>
+ <TT>
+ <P>
+ Other possible attributes in a copylist entry:</P>
+ <UL>
+ <LI>
+ <TT>notrequired</TT>
+ <LI>
+ <TT>newname="filename"</TT>
+ </LI>
+ </UL>
+ <P>By default, copylist entries are required and the script will die if they aren't
+ present. To ignore missing files, add <TT>notrequired</TT>.</P>
+ <P>To rename the file, set the <TT>newname</TT> attribute.</P>
+ <P>Lengthy copy lists can be kept in separate files and included with the Include
+ directive. Example:</P>
+ <P class="code"><Include path="sdkfiles.xml" /></P>
+ <H2><FONT face="Verdana"><A name="Remainingwork"></A>Remaining work / bug list</FONT></H2>
+ <P>This is a work in progress. What's left:</P>
+ <P>Bugs:</P>
+ <UL>
+ <LI>
+ <FONT face="Verdana">Eliminate need for redundant <TT>/debug debug</TT>. </FONT>
+ <LI>
+ <FONT face="Verdana">Handle checkout into non-existant directory.</FONT>
+ </LI>
+ </UL>
+ <H2><FONT face="Verdana"><A name="Troubleshooting"></A>Troubleshooting</FONT>
+ </TT></H2>
+ <P><TT><FONT face="Verdana"><STRONG>svn can't create tunnel:<BR>
+ </STRONG>Make sure environment variable SVN_SSH points to a valid
+ plink.exe. Path separators must be backslashes and must be doubled.</FONT></TT><TT></P>
+ </TT>
</DIV>
</BODY>
</HTML>
|