|
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 User Installation |
|
19 |
|
20 The configuration management team for the project you are working on will provide you with: |
|
21 |
|
22 =over 4 |
|
23 |
|
24 =item 1 |
|
25 |
|
26 A release tools distribution F<zip> file. |
|
27 |
|
28 =item 2 |
|
29 |
|
30 A project specific configuration file (named F<reltools.ini>). |
|
31 |
|
32 =back |
|
33 |
|
34 To install the tools, do the following: |
|
35 |
|
36 =over 4 |
|
37 |
|
38 =item 1 |
|
39 |
|
40 Unpack a release tools distribution F<zip> file into a directory that is present in your path environment variable (or to a new directory and add this to your path). |
|
41 |
|
42 =item 2 |
|
43 |
|
44 Set up a blank development area. Usually, this would be a substituted drive, but the EPOCROOT and SRCROOT environment variables are supported if you wish to use another mechanism. At this time, the @sdk syntax is not supported - you must explicitly set your EPOCROOT variable. The SRCROOT is assumed to be \ if it is not specified. |
|
45 |
|
46 =item 3 |
|
47 |
|
48 Copy the F<reltools.ini> file into F<\epoc32\relinfo> in the drive you plan to do development for this project in. This drive should (prior to this) be completely empty. Note, if you are working on more than one project, each development drive must have its own configuration file. |
|
49 |
|
50 =item 4 |
|
51 |
|
52 If you plan to use the C<DiffRel> command, you will need to add a line to F<reltools.ini> that specifies the name of the differencing tool to use, e.g.: |
|
53 |
|
54 diff_tool windiff |
|
55 |
|
56 Note, the tool specifed must be capable of differencing the contents of a pair of directories given their names as command line arguments. |
|
57 |
|
58 =back |
|
59 |
|
60 =head1 Perl Versions |
|
61 |
|
62 The tools should work with Perl 5.005 or higher. |
|
63 |
|
64 Some tools, notably C<CheckBc>, require Perl version 5.6.1 or higher. This is avaialble from www.activestate.com. Any tools requiring this version of Perl will simply refuse to run: you need not worry about incorrect operation. |
|
65 |
|
66 At this time, Perl 5.8.0 has bugs and is not recommended. |
|
67 |
|
68 =head1 Full Configuration |
|
69 |
|
70 This section describes how to perform a full configuration of the release tools for a particular project. This task is generally undertaken by the project's configuration management team at the start of the project. However as the project evolves, its release structure is likely to evolve also, and so this section also provides the information necessary to maintain existing configuration files. |
|
71 |
|
72 =head2 reltools.ini |
|
73 |
|
74 The file F<reltools.ini> must be distributed in the same directory as the rest of the tools. In may contain the following configuration keyword / value pairs (note, the keywords are case sensitive). |
|
75 |
|
76 Text after # is assumed to be a comment, unless the comment is preceded by \ in which case the # is literal. |
|
77 |
|
78 =over 4 |
|
79 |
|
80 =item * archive_path_file <file_name> |
|
81 |
|
82 =item * archive_path <project_name> <local_path> <remote_path> |
|
83 |
|
84 These keywords are used to inform the tools where to keep releases on the local and remote archives. See the section I<Archive Path> for full details. The first syntax (C<archive_path_file>) is the older style, and specifies where to find a file listing the exact location of each component. This may be a UNC style path to a file on a network share. The newer style lists several areas that the release tools should search to find a particular release. |
|
85 |
|
86 You must either have a single C<archive_path_file> line, or at least one C<archive_path> line. You cannot use both. |
|
87 |
|
88 =item * source_map <archive_source_directory> <local_source_directory> |
|
89 |
|
90 Defines source mappings which are to be applied to a release when using the release tools. A source mapping enables source directories to be extracted, from an archive, to specified locations on the working drive. Enables working on a release which has mapped source. Enables the user to make releases from a mapped location on the working drive to be stored with a specified directory structure in the archive. |
|
91 |
|
92 =item * export_data_file <file_name> |
|
93 |
|
94 Specifies the name of the project's export data file (see the section I<Export Data File>) path to a file on a network share. Use of this keyword is mandatory. |
|
95 |
|
96 =item * require_internal_versions |
|
97 |
|
98 Normally C<MakeRel> and C<MakeEnv> allow internal versions of releases to be optionally specified. If this keyword is present, they will insist that an internal version is specified. |
|
99 |
|
100 =item * ignore_source_filter_errors |
|
101 |
|
102 C<MakeRel> and C<MakeEnv> filter a releases source into C<zip> files corresponding to different categories. The tools can then be configured to restrict access to certain categories of source for each licensee/third party involved in the project. Currently the method for filtering source is to use C<iprtool>. By default, errors occuring during filtering will be stored in the releases C<reldata> file (and shown in the release notes). If this keyword is present, source filter errors will not be stored or shown. |
|
103 |
|
104 =item * disallow_unclassified_source |
|
105 |
|
106 By default, unclassified source (i.e. source directories that don't contain a F<distribution.policy> file detailing the source category) is classified as category 'X'. If this keyword is present, then unclassified source will generate an error when an attempt to release it is made (using either C<MakeRel> and C<MakeEnv>). |
|
107 |
|
108 =item * no_ini_location_warning |
|
109 |
|
110 By default the tools expect to find the F<reltools.ini> file in F<\epoc32\relinfo>. This is so a single installation of the tools can be used with multiple projects. However, if the file is not found there, it is looked for in the directory the tools are running from. If found, it will be used, but by default a warning is displayed to alert the user that they may be not using the configuration they had intended to use. To disable this warning, specify this keyword in the F<ini> file. |
|
111 |
|
112 =item * disable_win32_extensions |
|
113 |
|
114 By default the tools make use of various Win32 Perl modules. These have been found to be faulty on certain Perl releases and so this keyword can be used to disable functionality that depends on them. For the most part, disabling the functionality that uses Win32 will not result in reduced overall functionality, but certain operations may take longer to process. However, when they are disabled the tools will not be able to protect themselves against the user running commands concurrently in an unsafe way. It is therefore advisable to leave Win32 extensions enabled unless there is a good reason not to do so. |
|
115 |
|
116 =item * categorise_binaries |
|
117 |
|
118 By default component releases contain a single F<zip> file that holds all the released binaries. If this keyword is specified, the tools will categorise the binaries by build variant (e.g. C<wins udeb>, C<test thumb urel>, etc.). Having done this, the C<required_binaries> keyword can be used to choose a sub-set of the available binaries for a particular project. Note, this keyword can also be spelt C<categorize_binaries>. Note also, this keyword has only existed since release 2.50 of the tools. Any releases generated using categorised binaries must be installed using a version of the tools >= 2.50. |
|
119 |
|
120 =item * categorise_exports |
|
121 |
|
122 By default component exports (header files etc.) are included in the main binaries F<zip> file of each component release. This means that they are available to all parties that have access to the corresponding releases. If this keyword is specified, the tools will categorise exports according to the same rules as source code. This allows access to exports to be restricted in the same way as for source code (see the section F<Export Data File> below). Note, this keyword can also be spelt C<categorize_exports>. Note also, this keyword has only existed since release 2.59 of the tools. Any releases generated using categorised exports must be installed using a version of the tools >= 2.59. |
|
123 |
|
124 =item * required_binaries <component> <build_description> |
|
125 |
|
126 By default all available categories of binaries will be installed (when using C<GetRel> and C<GetEnv>) and exported (when using C<ExportRel> and C<ExportEnv>). This keyword can be used to choose a sub-set of the available binary categories (assuming that C<categorise_binaries> was used when the corresponding releases were made, if it wasn't then it will have no effect and you'll get everything). The C<component> argument may be either a valid component name or C<default> which applies to all components. This allows the general policy to be defined using C<default> and exceptions to be defined using specific component names. The C<build_description> argument must be a string made up from valid build commands, separated by underscore ('C<_>') characters. For example, to specify C<thumb> (both C<udeb> and C<urel>) and C<wins udeb> for all components, do: |
|
127 |
|
128 required_binaries default thumb |
|
129 required_binaries default wins_udeb |
|
130 |
|
131 To override the defaults for the component C<wserve> to C<armi urel> also, add: |
|
132 |
|
133 required_binaries wserv thumb |
|
134 required_binaries wserv wins_udeb |
|
135 required_binaries wserv armi_urel |
|
136 |
|
137 To override the defaults for the component C<e32test> to just C<arm4> test code (both C<udeb> and C<urel>), add: |
|
138 |
|
139 required_binaries e32tools test_arm4 |
|
140 |
|
141 =item * html_notes |
|
142 |
|
143 Specifies the behaviour of the tools when displaying the release notes of components made with versions of the tools prior to v2.83.1014, whether to treat text as HTML (thereby allowing tags) or to render notes as plain text (in v2.nn.nn support for the <html> tags to specify whether text is HTML or not was added). |
|
144 |
|
145 =item * remote_site_type <server_type> |
|
146 |
|
147 Specifies the type of server hosting the projects remote archive used to share releases between different sites. Must be C<FTP> for an FTP server, C<proxy> for an FTP proxy server, C<NetDrive> for a network drive, C<MultiVolumeExport> to export multiple fixed size volumes, C<MultiVolumeImport> to import multiple volumes. |
|
148 |
|
149 =item * remote_host <host_name> |
|
150 |
|
151 Specifies host name of the remote site where the remote archive is stored. This will be a DNS or IP address if the remote site is an FTP site or a UNC path (ie \\server\share) if the remote site is a network drive. |
|
152 |
|
153 =item * remote_username <username> |
|
154 |
|
155 Specifies the username required to access the remote site. Not required if the remote site is a network drive. |
|
156 Also, not mandatory - if it is not specified in C<reltools.ini> then it will be prompted for when it is needed. |
|
157 |
|
158 =item * remote_password <password> |
|
159 |
|
160 Specifies the password required to access the remote site. Not required if the remote site is a network drive. |
|
161 Also, not mandatory - if it is not specified in C<reltools.ini> then it will be prompted for when it is needed. |
|
162 |
|
163 =item * remote_logs_dir <directory> |
|
164 |
|
165 An optional keyword which specifies a directory on the remote host in which to write a log of releases that have been successfully exported. The log is an empty file with a name composed of the component name and version. |
|
166 |
|
167 =item * pasv_transfer_mode |
|
168 |
|
169 If this keyword is specified and the remote site is an FTP server (or proxy) then the tools will connect to the server in passive mode. Passive mode is required to access some FTP sites (behind firewalls for example). If the export/import tools freeze after connecting then try using this keyword. |
|
170 |
|
171 =item * ftp_server_supports_resume |
|
172 |
|
173 If this keyword is specified and the remote site is an FTP server (or proxy) then the tools will attempt to reconnect and resume an export or import if the FTP connection is dropped during a file transfer. Some FTP servers may not support this feature so the default behaviour is to fail the export/import if the connection is dropped. |
|
174 |
|
175 =item * ftp_timeout |
|
176 |
|
177 Specifies the timeout (in seconds) for a connection to an FTP server. This should be set to higher values for poor connections. If not set a default value is chosen. |
|
178 |
|
179 =item * ftp_reconnect_attempts |
|
180 |
|
181 Specifies the number of attempts made to reconnect to an FTP server after the connection is dropped. This should be set to higher values for poor connections. If not set a default value is chosen. |
|
182 |
|
183 =item * proxy <host_name> |
|
184 |
|
185 Specifies the IP address or DNS name of an FTP proxy server used to access the FTP site containing the remote archive. |
|
186 |
|
187 =item * proxy_username <username> |
|
188 |
|
189 Specifies the username required to access the proxy server. |
|
190 Not mandatory - if it is not specified in C<reltools.ini> then it will be prompted for when it is needed. |
|
191 |
|
192 =item * proxy_password <password> |
|
193 |
|
194 Specifies the password required to access the proxy server. |
|
195 Not mandatory - if it is not specified in C<reltools.ini> then it will be prompted for when it is needed. |
|
196 |
|
197 =item * max_export_volume_size <size_in_bytes> |
|
198 |
|
199 This keyword relates to remote sites of type C<MultiVolumeExport>. It can be used to specify the maximum size an export volume may reach before then next one is started. By default a value of 670040064 (639 MB) is used, appropriate for volumes that will be transferred to CD. |
|
200 |
|
201 =item * pgp_tool <tool_name> |
|
202 |
|
203 The name of the command line PGP tool used to encrypt releases for export and decrypt imported releases. This must be set to either C<PGP> for Network Associates command line PGP (version 6 and 7) or C<GPG> for GNU Privacy Guard PGP tool (version 1.06). |
|
204 |
|
205 =item * pgp_encryption_key <keyid> |
|
206 |
|
207 Specifies the ID (an 8 digit hexadecimal number preceeded by C<0x> e.g C<0x8AF34E21>) of a PGP key which will be used to encrypt all release files before exporting to the remote site. This keyword may be used many times with each value being added to a list of key ids. Typically the value of this keyword will be set to the local teams project key id so that they may decrypt their own exported releases. |
|
208 |
|
209 =item * pgp_config_path <dir_name> |
|
210 |
|
211 Specifies the directory where the users PGP configuration and keyring files are stored. If not set the default value for the PGP tool will be used. |
|
212 |
|
213 =item * ignore_binary <wild_file_name> |
|
214 |
|
215 Specifies files in the F<\epoc32> tree that should be disregarded from the point of view of unknown origin status when an environment scan is performed (scans are done by C<EnvInfo>, C<MakeEnv> and C<CleanEnv>). As standard, the following are ignored (this keyword can be used to add to this list): |
|
216 |
|
217 \epoc32\relinfo\* |
|
218 \epoc32\build\* |
|
219 \epoc32\wins\c\* |
|
220 \epoc32\release\*.ilk |
|
221 \epoc32\release\*.bsc |
|
222 \epoc32\data\emulator\*.sys.ini |
|
223 |
|
224 Note, the only wild character supported is C<*>, and this is 'greedy'. For example, F<\epoc32\build\*> ignores everything in F<\epoc32\build> and all it's sub-directories. F<\epoc32\release\*.ilk> ignores any file ending in F<.ilk> in F<\epoc32\release> and all it's sub-directories. |
|
225 |
|
226 =item * diff_tool |
|
227 |
|
228 The tool that C<diffrel> should use to compare two releases. |
|
229 |
|
230 =item * table_format |
|
231 |
|
232 The format of the tables produced by the Release Tools. If omitted, text format is used. Tables are produced by many commands, such as C<envinfo>, C<bininfo>, C<latestver> and C<sourceinfo>. These can be difficult to view if the tables are too wide to fit in your terminal. Using this keyword selects an alternative table format. Use one of these options: text, CSV, HTML, Excel or Auto. "Auto" takes an extra argument, for example: |
|
233 |
|
234 table_format auto excel |
|
235 |
|
236 It prompts the tools to show small tables as text, but to use Excel if they are too wide to fit, or have more than a certain number of rows. For normal usage, we recommend "auto excel" or "auto html" because they both auto-fit the column widths and produce easily legible tables. |
|
237 |
|
238 =back |
|
239 |
|
240 Here's an example F<reltools.ini> file: |
|
241 |
|
242 require_internal_versions |
|
243 disallow_unclassified_source |
|
244 categorise_binaries |
|
245 categorise_exports |
|
246 diff_tool windiff |
|
247 table_format auto excel |
|
248 archive_path pixiework \\pixieshare\config_man\archive\pixiestuff /share/archive/pixiestuff |
|
249 archive_path ourwork \\pixieshare\config_man\archive\ourstuff /share/archive/ourstuff |
|
250 archive_path hurricane \\pixieshare\config_man\archive\hurricane /share/archive/hurricane |
|
251 export_data_file \\pixieshare\config_man\reltools\export_data.csv |
|
252 pgp_tool PGP |
|
253 pgp_encryption_key 0x12345678 |
|
254 pgp_config_path \\pixieshare\config_man\reltools\ |
|
255 remote_site_type FTP |
|
256 remote_host ftp.pixie.com |
|
257 remote_username myusername |
|
258 remote_password mypassword |
|
259 remote_logs_dir /release_logs |
|
260 proxy myproxyhost |
|
261 proxy_username myproxyusername |
|
262 proxy_password myproxypassword |
|
263 pasv_transfer_mode |
|
264 ftp_server_supports_resume |
|
265 ftp_timeout 60 |
|
266 ftp_reconnect_attempts 5 |
|
267 required_binaries default wins_udeb |
|
268 required_binaries default thumb_urel |
|
269 |
|
270 =head2 Archive Path |
|
271 |
|
272 The release tools must know where to find (and put) a release, both on the local and remote archives. This information is used primarily whenever a release is made, exported or installed. There are two alternative mechanisms for supplying this information to the release tools. You should choose one or the other. |
|
273 |
|
274 =over 4 |
|
275 |
|
276 =item Old-style Archive Path File |
|
277 |
|
278 Some licensees want a single file that lists the exact location of each component. The problem with this arrangement is that the file must be altered if a component moves from one place in the archive to another - which typically happens whenever a Symbian component is branched for the first time, or if responsibility for a component moves from one organisation to another. |
|
279 |
|
280 If you use a single archive path file, its location should be specified with the C<archive_path_file> keyword in the F<reltools.ini> file. It is recommended that a single copy of this file be placed on a network share, and referred to by the F<reltools.ini> file in the project's release tools distribution F<zip>. This will allow the file to be maintained without having to roll out a new distribution of the release tools. It is also advisable to restrict write access to the file to ensure it doesn't get changed in error. |
|
281 |
|
282 The archive path file exists to allow sites flexibility in the way their releases are archived. It also allows the maintainer of a remote host to allocate each site that will be delivering software their own directory with appropriate permissions. |
|
283 |
|
284 The file must contain lines in the following format: |
|
285 |
|
286 <component_name> <local_archive_path> <remote_archive_path> |
|
287 |
|
288 It is also possible to specify a default path, to be used if the paths for a component have not been specified with the above syntax: |
|
289 |
|
290 default <local_archive_path> <remote_archive_path> |
|
291 |
|
292 Here's an example archive path file: |
|
293 |
|
294 # Miscellaneous components. |
|
295 default \\pixieshare\release_archive\misc /mycompany/pixie/misc |
|
296 |
|
297 # Components delivered by our company. |
|
298 comp1 \\pixieshare\release_archive\mycompany /mycompany/pixie |
|
299 comp2 \\pixieshare\release_archive\mycompany /mycompany/pixie |
|
300 |
|
301 # Components delivered by other companies. |
|
302 comp3 \\pixieshare\release_archive\company_x /company_x/pixie |
|
303 comp4 \\pixieshare\release_archive\company_y /company_y/pixie |
|
304 |
|
305 =item New-style Archive Paths |
|
306 |
|
307 The new mechanism fulfils the same purpose, but with additional flexibility. The release tools will search several areas for a particular release of a component. This allows components to be branched, or experimentally modified by several organisations, without the need to constantly adjust an F<archive_path.txt> file. |
|
308 |
|
309 With this mechanism, there is no F<archive_path.txt> file. Instead, statements in the F<reltools.ini> provide all the necessary information. These should appear as: |
|
310 |
|
311 archive_path <project_name> <local_path> <remote_path> |
|
312 |
|
313 You would normally have several such lines, listing different areas to search. Each one should belong to one organisation, though an individual may even have their own repository. The project name is just a label, and is reported by various commands such as C<envinfo -f> depending on where the release is stored. |
|
314 |
|
315 archive_path pixiework \\pixieshare\config_man\archive\pixiestuff /share/archive/pixiestuff |
|
316 archive_path ourwork \\pixieshare\config_man\archive\ourstuff /share/archive/ourstuff |
|
317 archive_path hurricane \\pixieshare\config_man\archive\hurricane /share/archive/hurricane |
|
318 |
|
319 The directories are searched in the order they are listed; so if a gnome 002 exists in several places, the first one will be used. All releases are made into the first listed directory by default, though you can choose to place them into another project with the C<-w> switch to C<makerel> and C<makeenv>. When exporting, the release tools will put a release in the remote directory that corresponds to the relevant local directory. The same applies when importing. |
|
320 |
|
321 Ideally, all the local and remote paths will be different. However, if you're constained by an existing archive structure, you might want different projects to have different local archive paths, and the same remote archive path (or vice versa). In this case, when importing (for example) the release tools may have several possible local directories that they can put a release in. They always choose the one listed first in the F<reltools.ini>. |
|
322 |
|
323 =back |
|
324 |
|
325 =head2 Export Data File |
|
326 |
|
327 In order to use the commands C<ExportEnv> and C<ImportEnv> an export data file must be written and indicated in F<reltools.ini> with the C<export_data_file> keyword. A project's export data file contains a table detailing the source categories each site can have access to for each component. The raw data format of the file must be CSV (comma separated variables), but it is recommended that a spreadsheet such as Excel is used to prepare this to make sure data is in the correct columns. It is also recommended that a single copy of this file be placed on a network share, and referred to by the F<reltools.ini> file in the project's release tools distribution F<zip>. This will allow the file to be maintained without having to roll out a new distribution of the release tools. It is also advisable to restrict write access to the file to ensure it doesn't get changed in error. |
|
328 |
|
329 Here's an example layout: |
|
330 |
|
331 | pgpkeyid_1 (recipient) | pgpkeyid_2 (recipient) | pgpkeyid_3 (recipient) | |
|
332 ------------+------------------------+------------------------+------------------------+-- |
|
333 component_1 | DE | E | CDE | |
|
334 ------------+------------------------+------------------------+------------------------+-- |
|
335 component_2 | CDE | | DE | |
|
336 ------------+------------------------+------------------------+------------------------+-- |
|
337 component_3 | DE | E | exclude | |
|
338 ------------+------------------------+------------------------+------------------------+-- |
|
339 component_4 | exclude_bin DEFG | DEFG | DEFG | |
|
340 |
|
341 |
|
342 |
|
343 The column headers must contain the recipients PGP key ID - an eight digit hexadecimal number preceeded by C<0x> (e.g C<0xD9A2CE15>). This public PGP key will be used to encrypt all files sent to the recipient. The name of the recipient may also be included in the column header although this is not mandatory. |
|
344 |
|
345 A cell contains a list of source categories available to the recipient of the component. |
|
346 Each category must be a single letter or digit. Empty cells imply that the recipient |
|
347 does not have access to any source for the corresponding component but can still receive |
|
348 binaries. |
|
349 |
|
350 To prevent a recipient from receiving both source and binaries for the corresponding component, use the keyword C<exclude>. This can be useful when certain recipients may receive releases of some but not all components. |
|
351 |
|
352 To prevent a recipient from receiving binaries for the corresponding component, use the keyword C<exclude_bin>. Unlike C<exclude>, this does not break any environment. |
|
353 |
|
354 Components which are not listed in the table but exist on the local site will not be exported to any recipients. However, a warning will be issued to alert the exporter of this situation. |
|
355 |
|
356 If a licensee or third party does not use C<DISTRIBUTION.POLICY> files to categorize source then all source will have the category X. In this case, putting X in a cell implies that all source for that component will be sent to the recipient, otherwise none will be sent. |
|
357 |
|
358 Lines starting with a C<#> are treated as comments and ignored. |
|
359 |
|
360 [NOTE: It is recommended that this file is created and maintained using a spreadsheet |
|
361 application (saving as a CSV file) rather than editing it directly.] |
|
362 |
|
363 =head1 COPYRIGHT |
|
364 |
|
365 Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
366 All rights reserved. |
|
367 This component and the accompanying materials are made available |
|
368 under the terms of the License "Eclipse Public License v1.0" |
|
369 which accompanies this distribution, and is available |
|
370 at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
371 |
|
372 Initial Contributors: |
|
373 Nokia Corporation - initial contribution. |
|
374 |
|
375 Contributors: |
|
376 |
|
377 Description: |
|
378 |
|
379 |
|
380 =cut |