|
1 #!perl |
|
2 # Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 # All rights reserved. |
|
4 # This component and the accompanying materials are made available |
|
5 # under the terms of the License "Eclipse Public License v1.0" |
|
6 # which accompanies this distribution, and is available |
|
7 # at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 # |
|
9 # Initial Contributors: |
|
10 # Nokia Corporation - initial contribution. |
|
11 # |
|
12 # Contributors: |
|
13 # |
|
14 # Description: |
|
15 # |
|
16 # |
|
17 |
|
18 =head1 Overview |
|
19 |
|
20 This document discusses the various techniques that can be used to make component releases. It describes the files that specify what comprises a component release (F<mrp> files), and then how these can be used to produce release packets. |
|
21 |
|
22 =head1 Location |
|
23 |
|
24 Before you start, you should know where you want to store your release. The release tools support two structures of local archive - "component-based" and "project-based". If you're using the old-style, component-based structure, then skip this section since you have no choice where your release will be stored. (You can find out by seeing if you have an C<archive_path_file> line in your F<reltools.ini>.) |
|
25 |
|
26 If you are using the new-style, project-based, archive structure, then there may be several places you could store your release in the archive. These are called "projects", and may be something like "GT" or "LPD", or perhaps a licensee name. Any development you do should be stored in your own project, even if you've modified somebody else's component. |
|
27 |
|
28 For both C<makerel> and C<makeenv> commands, described later, you can optionally specify a project location with the C<-w> switch. If you don't, the release will be made to your default project which is the first one listed in your F<reltools.ini> file. |
|
29 |
|
30 =head1 Mrp Files |
|
31 |
|
32 Each component to be released must have a corresponding F<mrp> file. Normally this would be archived in the source code of the component. F<mrp> files can be automatically generated using the tool C<GenMrp>, but normally a certain amount of hand tuning will be required (to select the exact binary targets required, for example). The F<mrp> parser understands the following statements: |
|
33 |
|
34 =over 4 |
|
35 |
|
36 =item * component <component_name> |
|
37 |
|
38 The name that will be used to refer to this component when using the release tools. Can be used only once per F<mrp>. |
|
39 |
|
40 =item * source (<source_file> | <source_directory>) |
|
41 |
|
42 Used to describe which source files should be put into a release. May be used more than once in a single F<.mrp> file (or not at all). If a directory is specified, all files in that directory and it's sub-directories will be included in the release. |
|
43 |
|
44 The specified paths may be absolute or relative. If they're relative, then they're relative to the location of the MRP. If they're absolute (start with a backslash) then they are assumed to be relative to the SRCROOT environment variable. If there's no SRCROOT environment variable, then a source root of \ is assumed. |
|
45 |
|
46 =item * [-]binary (<abld_path> <platform> [<variant> [<program>]]) | <binary_file> | <binary_directory> |
|
47 |
|
48 Used to describe which binary files should be put into a release. May be used more than once in a single F<.mrp> file (or not at all). The first argument structure (<abld_path> <platform> [<variant> <program>]) directs the Release Tools to enquire from the EPOC build tools which binaries should be included in the release. The <abld_path> argument should provide the full path to the directory where the component's <abld.bat> file lives. This will be the same directory as the component's <bld.inf> file. <platform> and <build_cmnd_1> ... <build_cmnd_n> must be valid for the corresponding <bld.inf> file (common choices would be C<wins udeb> and C<thumb urel>). You can also use the keyword all, which will read all the platforms supported by the <bld.inf> and include all of them (for both udeb and urel). Note, you can also specify the name of an individual F<mmp> file (or program), for example C<thumb urel mymmp>. |
|
49 |
|
50 The second and third argument structures allow individual binary files and directories of binary files to be specified (as with the C<source> keyword, directories are recursively scanned). These forms of C<binary> statement should only be used if the first cannot be. However, with the EPOC build tool's support for custom make files, it is highly unlikely that this would ever be the case. If using a custom make file, be sure to provide a C<RELEASABLES> target, because this is how the release tools get the information they need. |
|
51 |
|
52 The C<binary> keyword can be preceded with a minus sign (C<->). This instructs the release tools to exclude the associated binaries from the release. You may therefore first use a C<binary> statement to specify more than you actually want to release, and and then a C<-binary> statement to refine the list. For example: |
|
53 |
|
54 binary \mycomp wins udeb |
|
55 -binary \mycomp wins udeb mymmp_to_exclude |
|
56 -binary \myfile_to_exclude |
|
57 |
|
58 Paths referring to <bld.inf> files are relative to SRCROOT, using the same rules as described in L<source>. Paths referring to binary files must be absolute, and are assumed to be within EPOCROOT. |
|
59 |
|
60 =item * [-]testbinary <abld_path> <platform> [<variant> [<program>]] |
|
61 |
|
62 Used to describe which test binary files should be put into a release. Identical to the first argument structure of the C<binary> keyword, except for use with test code. Also supports a preceeding minus sign (C<->) to allow the exclusion of certain programs. |
|
63 |
|
64 =item * exports <abld_path> |
|
65 |
|
66 Used to describe which exports (header files etc.) should be included. Note, by default exports are treated as though they are binary files unless the C<categorise_exports> keyword is specified in the F<reltools.ini>. This means that they are made available to all sites that are able to receive the binaries. If exports are categorised, they are given the same IPR category as the corresponding source file. See the F<Installation> section for details. |
|
67 |
|
68 This keyword can be used more than once. If the component's F<bld.inf> file lists more exports than are required, specific files may be removed from the export list using the C<-export_file> keyword. See below. Note, prior to release 2.59 of the tools, it was recommended that the keyword C<-binary> be used for this purpose. This is semantically identical when the C<categorise_exports> F<reltools.ini> keyword is B<not> used, however it has no effect when it is. |
|
69 |
|
70 =item * [-]export_file <source_export_file> <destination_export_file> |
|
71 |
|
72 Used to manually specify exported files. Note, both source and destination export file names must be specified. The source export file name is needed to assign the export's IPR category to that of the corresponding source file. The source file must therefore be present within the source tree specified using C<source> keywords. If this is not the case, an error will be thrown when the F<mrp> file is parsed. |
|
73 |
|
74 Note that the source and destination locations' arguments' relativity is the same as for the <source> keyword and the <binary file> keyword respectively. This is as you would expect. |
|
75 |
|
76 =item * notes_source <release_notes_source_path> |
|
77 |
|
78 Information regarding the content of a release should be provided in the form of a release notes source file. This will be stored with the release in a format that can be compiled in to HTML using the tool C<ViewNotes>. The C<notes_source> keywork is used to specify where this source file can be found. The location is assumed to be within the source code, and follows the same rules for relative and absolute paths as described above in L<source>. The following keywords are supported (the text beneath each keyword will be compiled into the release notes): |
|
79 |
|
80 =over 8 |
|
81 |
|
82 =item * notesrc_releaser |
|
83 |
|
84 The name of the person making the release. |
|
85 |
|
86 =item * notesrc_release_reason |
|
87 |
|
88 A description of why the release was made (e.g. "Defect fix to alpha candidate"). |
|
89 |
|
90 =item * notesrc_general_comments |
|
91 |
|
92 A summary of the release conent, including any information that it is particularly important others should read (e.g. "Interface X has been depricated in this release, please use Y instead. The reason for this was..."). |
|
93 |
|
94 =item * notesrc_known_deviations |
|
95 |
|
96 A list of areas where this component is known to not conform to spec. (e.g. "Feature X is currently not working because defect Y needs to be fixed in component Z"). |
|
97 |
|
98 =item * notesrc_bugs_fixed |
|
99 |
|
100 A list of defects fixed in this release (ideally including the defect reference code and description). |
|
101 |
|
102 =item * notesrc_bugs_remaining |
|
103 |
|
104 A list of known defects outstanding in this release (again, ideally including the defect reference code and description). |
|
105 |
|
106 =item * notesrc_other_changes |
|
107 |
|
108 A list of other changes made to the component (e.g. new features). |
|
109 |
|
110 =back |
|
111 |
|
112 =back |
|
113 |
|
114 Here's an example F<.mrp> file: |
|
115 |
|
116 component mycomp |
|
117 source \mycomp |
|
118 binary \mycomp\group wins udeb |
|
119 binary \mycomp\group thumb urel |
|
120 exports \mycomp\group |
|
121 notes_source \mycomp\group\release.src |
|
122 |
|
123 =head1 Making a Single Component Release |
|
124 |
|
125 The command C<MakeRel> can be used to create a single component release. It is assumed that the binaries to be released have already been built and tested. The following command... |
|
126 |
|
127 makerel mycomp 001 |
|
128 |
|
129 ...instructs C<MakeRel> to read the F<mrp> file F<mycomp.mrp> (note, specifying the F<mrp> extension is optional) and generate a release packet with the version 001. If C<mycomp> version C<001> already exists, an error will be generated. Also, if any of the binaries referred to by the F<mrp> file do not exist, an error will be generated. The release will be put into the component's archive (specified in the project's archive path file, see the document I<Installation Guide> for details). Once a release has been made, the command C<GetRel> can be used to retrieve it. |
|
130 |
|
131 =head1 Making Multiple Component Releases |
|
132 |
|
133 C<MakeRel> can also be used to create more than one component release in one pass. The various F<mrp> file names and versions must be specified in a text file with lines in the following format: |
|
134 |
|
135 <mrp_name> <version> [<internal_version>] |
|
136 |
|
137 C<MakeRel> can then be envoked as follows: |
|
138 |
|
139 makerel mycomps.txt |
|
140 |
|
141 This technique can be useful when preparing the first set of releases for a project. However, where ever possible the command C<MakeEnv> should be used rather than C<MakeRel> because this performs a rigorous check of the environment to ensure it can be reliably reproduced in it's entirety. |
|
142 |
|
143 =head1 Making an Environment Release |
|
144 |
|
145 Releasing an environment involves releasing one or more components in a way that ensures the entire F<\epoc32> in which they currently reside can be reproduced. The command C<MakeEnv> is used to do this, which makes heavy use of the drive's environment database (this is a binary file stored on the current drive in F<\epoc32\relinfo>). Whenever a component is installed, upgraded or removed from an environment, the drive's environment database is updated. At any point in time, the environment database should contain an up to date list of versions of each component installed. The command C<EnvInfo> displays this information on the screen in a table. Using C<EnvInfo>'s C<-ff> switch, a fuller table can be displayed, for example: |
|
146 |
|
147 Component Version Internal version Status Mrp |
|
148 |
|
149 mycomp1 026 //myproject/latest/mycomp1/...@10106 dirty \mycomp1\mycomp1.mrp |
|
150 mycomp2 057 //myproject/latest/mycomp1/...@10157 clean \mycomp2\mycomp2.mrp |
|
151 |
|
152 Overall status: dirty |
|
153 |
|
154 The status column shows the current status of each component currently installed. A status of C<clean> means that the component's binaries can be reproduced (this is determined by comparing the current time stamps of the files against as set that was stored when the component was installed (the component's I<signature>)). A status of C<dirty> means that the binaries cannot be reproduced. If any components have a status of C<dirty>, then the overall status of the environment will be C<dirty>. It is not possible to use C<MakeEnv> to release components whilst the environment is in a dirty state. In order to release the environment, all dirty components must have their status changed to C<pending release>. This may be done for a single component using the command C<PrepRel>: |
|
155 |
|
156 preprel mycomp1 version [internal_version] |
|
157 |
|
158 Note, an internal version can be optionally specified. This will appear in the component's release notes, and may be of use for referrencing a configuration within a source control repository, for example. The command C<PrepEnv> can be used to prepare more than one component for release in one step. |
|
159 |
|
160 Even if all the components installed have a status of either C<clean> or C<pending release>, the overall status will be C<dirty> if there are files in the F<\epoc32> tree that are of unknown origin to the release tools, i.e. files that have not already been released by the C<clean> components, and will not be released by the C<pending release> components. In this situation one or more F<mrp> files will need to be changed to capture these files, or they will need to be removed from the environment before it can be released. Once C<EnvInfo> reports that the environment has an overall status of C<pending release>, the command C<MakeEnv> can be used to generate the releases. This command need not take any parameters, but using the C<-v> switch instructs it to be verbose about its activities. |
|
161 |
|
162 Once C<MakeEnv> has been run, other people in the same site may access the environment using C<GetEnv>. To provide remote sites access, the releases must first be encrypted and put on the project's FTP site. This is done using the command C<ExportEnv>. Other sites can then use the command C<ImportEnv> to bring the new releases into their local archive (see the document I<Installation Guide> for details of how to configure the release tools to do exporting and importing). |
|
163 |
|
164 =head1 Releasing the Output of a Build |
|
165 |
|
166 An individual site may have a build team whose role is to build and distribute the software being developed at that site. However, each time a build is performed, certain components may not have changed since the last time they were built. The command C<ValidateEnv> can be used to determine which components have changed and therefore need to be released. This is likely to significantly reduce the amount of data that must be transferred between sites (and ultimately down onto developer's workstations) compared to simply releasing everything each time. The following procedure is most commonly used: |
|
167 |
|
168 =over 4 |
|
169 |
|
170 =item 1 |
|
171 |
|
172 Install a reference environment using C<GetEnv> (this will be the environment against which C<ValidateEnv> will do its comparisons). |
|
173 |
|
174 =item 2 |
|
175 |
|
176 Install the source to be built (normally from a source control system). |
|
177 |
|
178 =item 3 |
|
179 |
|
180 Perform a clean build of the source, over writing the previously released binaries. |
|
181 |
|
182 =item 4 |
|
183 |
|
184 Test the resultant binaries, repeating step 3 until all problems have been resolved. |
|
185 |
|
186 =item 5 |
|
187 |
|
188 Run C<ValidateEnv> with no arguments. This will cause the binaries of each component currently installed to be unpacked into a temporary directory and compared with those in the current environment. The comparison is done by a tool that is able to ignore irrelevant differences between executables (such as data in headers). Any components that pass this comparison will have their signatures regenerated and their status set to C<clean>. Any component that fail this comparison will remain with a C<dirty> status. A list of components that failed will also be displayed at the end. |
|
189 |
|
190 =item 6 |
|
191 |
|
192 Use C<PrepEnv> or C<PrepRel> to set the status of all C<dirty> components to C<pending release>, assigning a new version to each. |
|
193 |
|
194 =item 7 |
|
195 |
|
196 Use C<MakeEnv> to release the environment. |
|
197 |
|
198 =back |
|
199 |
|
200 =head1 Trivia |
|
201 |
|
202 The file extension F<mrp> originates from the first version of the LPD release tools. It stood for B<M>C<ake>B<R>C<el> B<P>C<roject>, in keeping with the C<MakMake> file extension F<mmp>. Back then, the command C<MakeEnv> did not exist - C<MakeRel> was the only mechanism for making releases. The extension is retained now purely for historic reasons. |
|
203 |
|
204 =head1 COPYRIGHT |
|
205 |
|
206 Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
207 All rights reserved. |
|
208 This component and the accompanying materials are made available |
|
209 under the terms of the License "Eclipse Public License v1.0" |
|
210 which accompanies this distribution, and is available |
|
211 at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
212 |
|
213 Initial Contributors: |
|
214 Nokia Corporation - initial contribution. |
|
215 |
|
216 Contributors: |
|
217 |
|
218 Description: |
|
219 |
|
220 |
|
221 =cut |