Project

General

Profile

Dev concepts » History » Version 1

Marc Mengel, 07/05/2016 12:00 PM
auto-upload

1 1 Marc Mengel
2 1 Marc Mengel
| [[upsv4TOC| !{width:84px;height:23px}images/navtoc.gif(TOC)!  ]] | [[partproddev| !{width:81px;height:23px}images/navprev.gif(PREV)!  ]] | [[develop| !{width:81px;height:23px}images/navnext.gif(NEXT)!  ]] |
3 1 Marc Mengel
4 1 Marc Mengel
|.  !{width:60px;height:60px}images/CDlogo.gif(Fermilab CD logo)!  |\4. Complete Guide and Reference Manual for
5 1 Marc Mengel
UPS and UPD|
6 1 Marc Mengel
7 1 Marc Mengel
8 1 Marc Mengel
h3. Chapter Contents
9 1 Marc Mengel
10 1 Marc Mengel
11 1 Marc Mengel
p<>. [[dev_concepts#8346|Chapter 16: UPS Product Development: General
12 1 Marc Mengel
Considerations]] 
13 1 Marc Mengel
   [[dev_concepts#12914|16.1 Product Development
14 1 Marc Mengel
Considerations and Recommendations]] 
15 1 Marc Mengel
     [[dev_concepts#17335|16.1.1 All Products
16 1 Marc Mengel
(Locally Developed and Third Party)]] 
17 1 Marc Mengel
     [[dev_concepts#14504|16.1.2 Products that You
18 1 Marc Mengel
Develop]] 
19 1 Marc Mengel
     [[dev_concepts#40738|16.1.3 Third-Party
20 1 Marc Mengel
Products Requiring a Hard-Coded Path]] 
21 1 Marc Mengel
   [[dev_concepts#18733|16.2 Directory Structure for a UPS
22 1 Marc Mengel
Product Instance]] 
23 1 Marc Mengel
24 1 Marc Mengel
25 1 Marc Mengel
h1.  %(#8346)&nbsp;% Chapter 16: UPS Product
26 1 Marc Mengel
Development: General Considerations
27 1 Marc Mengel
28 1 Marc Mengel
29 1 Marc Mengel
p<>. %(#15554)&nbsp;% This chapter discusses the %{font-weight: bold;color: #000000}UPS% product development methodology and tools that can be
30 1 Marc Mengel
used in product development. It also provides recommendations for
31 1 Marc Mengel
organizing the local product development area and the individual
32 1 Marc Mengel
product root directories needed.
33 1 Marc Mengel
34 1 Marc Mengel
35 1 Marc Mengel
h2.  %(#12914)&nbsp;% 16.1 Product Development
36 1 Marc Mengel
Considerations and Recommendations
37 1 Marc Mengel
38 1 Marc Mengel
39 1 Marc Mengel
p<>. %(#13191)&nbsp;% This section provides
40 1 Marc Mengel
guidelines for product development as it affects the product's
41 1 Marc Mengel
inclusion in the %{font-weight: bold;color: #000000}UPS% framework.
42 1 Marc Mengel
43 1 Marc Mengel
p<>. %(#17303)&nbsp;% Simple scripts which run on any
44 1 Marc Mengel
architecture are straightforward to implement under %{font-weight: bold;color: #000000}UPS% . Products which are obtained from the outside world
45 1 Marc Mengel
(third party) as executable images with no source code are also
46 1 Marc Mengel
generally straightforward. The ones that get complicated are the
47 1 Marc Mengel
products which must be compiled and/or otherwise built for each and
48 1 Marc Mengel
every supported architecture.
49 1 Marc Mengel
50 1 Marc Mengel
51 1 Marc Mengel
h3.  %(#17335)&nbsp;% 16.1.1 All Products
52 1 Marc Mengel
(Locally Developed and Third Party)
53 1 Marc Mengel
54 1 Marc Mengel
55 1 Marc Mengel
h4.  %(#17317)&nbsp;% Shell Independence
56 1 Marc Mengel
57 1 Marc Mengel
58 1 Marc Mengel
p<>. %(#17331)&nbsp;% The product should run the same
59 1 Marc Mengel
way under both shell families, %{font-weight: bold;color: #000000}sh% and %{font-weight: bold;color: #000000}csh% . If the product requires any actions to take place
60 1 Marc Mengel
before it will run (e.g., its %{font-family: monospace}bin% directory added to $PATH, or
61 1 Marc Mengel
environment variables set), provide a table file containing
62 1 Marc Mengel
these actions. The %{font-weight: bold;color: #000000}UPS% environment is described in [[overview#8463|Chapter 2: %{font-weight: normal;color: #000000}Overview of UPS and UPD% ]] and table files in [[table_files#8463|Chapter 36: %{font-weight: normal;color: #000000}Table Files% ]] . The functions supported in table files are
63 1 Marc Mengel
designed to work in a shell-independent manner.
64 1 Marc Mengel
65 1 Marc Mengel
66 1 Marc Mengel
h4.  %(#17319)&nbsp;% Flavor Declaration in
67 1 Marc Mengel
UPS
68 1 Marc Mengel
69 1 Marc Mengel
70 1 Marc Mengel
p<>. %(#17332)&nbsp;% On your development system, we
71 1 Marc Mengel
recommend declaring products according to the %{font-weight: normal;color: #000000}fully specified flavor% of the machine on which
72 1 Marc Mengel
they were built. We consider this to be very
73 1 Marc Mengel
important, especially if the target systems contain or will ever
74 1 Marc Mengel
contain mixed OS releases (e.g., Linux+2.2 and Linux+2.5). This will
75 1 Marc Mengel
help to avoid problems when a new OS release doesn't run images
76 1 Marc Mengel
built on an older one, or vice-versa. It is difficult to go
77 1 Marc Mengel
back and try to figure out which OS release a particular product instance
78 1 Marc Mengel
was built for. It is better to be able to tell immediately from looking
79 1 Marc Mengel
at the database. Installers and users also need this information to
80 1 Marc Mengel
facilitate their database maintenance.
81 1 Marc Mengel
82 1 Marc Mengel
p<>. %(#17322)&nbsp;% Products which have no
83 1 Marc Mengel
flavor-dependence at all (shell scripts, for instance), should be
84 1 Marc Mengel
declared as NULL to the database (use the "zero" option, %{font-weight: bold;font-family: monospace}-0% ;
85 1 Marc Mengel
see [[options#8463|Chapter 25: %{font-weight: normal;color: #000000}Generic Command Option Descriptions% ]] ). For other
86 1 Marc Mengel
products, include the entire flavor string of the build platform in
87 1 Marc Mengel
the declaration, or the major portion of that string. For example,
88 1 Marc Mengel
if you build on an Linux machine running V2, declare your products
89 1 Marc Mengel
with the flavor Linux64bit+2 or Linux64bit+2.6 rather than just Linux64bit (e.g.,
90 1 Marc Mengel
use the flavor level corresponding to the options %{font-weight: bold;font-family: monospace}-4% or %{font-weight: bold;font-family: monospace}-3% or %{font-weight: bold;font-family: monospace}-2% rather than %{font-weight: bold;font-family: monospace}-1% )
91 1 Marc Mengel
92 1 Marc Mengel
93 1 Marc Mengel
h3.  %(#14504)&nbsp;% 16.1.2 Products that You
94 1 Marc Mengel
Develop
95 1 Marc Mengel
96 1 Marc Mengel
97 1 Marc Mengel
p<>. %(#14485)&nbsp;% If you're writing your own
98 1 Marc Mengel
product for implementation within %{font-weight: bold;color: #000000}UPS% , you have the luxury (and, we might add, the %{font-weight: normal;color: #000000}responsibility% ) of creating it such that it exploits the
99 1 Marc Mengel
important features of %{font-weight: bold;color: #000000}UPS% , thus making it easy for the user to install and run,
100 1 Marc Mengel
and easy for you or another developer to maintain in the future. We
101 1 Marc Mengel
urge you to follow the guidelines we present here.
102 1 Marc Mengel
103 1 Marc Mengel
104 1 Marc Mengel
h4.  %(#14508)&nbsp;% Self-Containment and
105 1 Marc Mengel
Location Determination
106 1 Marc Mengel
107 1 Marc Mengel
108 1 Marc Mengel
p<>. %(#14571)&nbsp;% First, design the product such
109 1 Marc Mengel
that it is self-contained. It should identify its location and the
110 1 Marc Mengel
location of any required files %{font-weight: normal;color: #000000}at run time% (as opposed to compile time). You as the product
111 1 Marc Mengel
developer have total control over the structure and contents of the
112 1 Marc Mengel
product root directory, but no control at all over where the
113 1 Marc Mengel
product root directory will reside on a target system.
114 1 Marc Mengel
115 1 Marc Mengel
p<>. %(#24638)&nbsp;%  !images/bombb.gif!  If
116 1 Marc Mengel
you write the product such that it calculates its location at
117 1 Marc Mengel
compile time, you'll be putting the hard-coded path to your
118 1 Marc Mengel
development environment into the image -- most likely %{font-weight: normal;color: #000000}not% the correct path on the user machine.
119 1 Marc Mengel
120 1 Marc Mengel
p<>. %(#19127)&nbsp;% 
121 1 Marc Mengel
122 1 Marc Mengel
123 1 Marc Mengel
h4.  %(#14507)&nbsp;% Reproducible Build
124 1 Marc Mengel
Procedure
125 1 Marc Mengel
126 1 Marc Mengel
127 1 Marc Mengel
p<>. %(#19464)&nbsp;% All products should be built
128 1 Marc Mengel
using a build script in order to ensure that the build procedure is
129 1 Marc Mengel
reproducible.
130 1 Marc Mengel
131 1 Marc Mengel
132 1 Marc Mengel
h4.  %(#14595)&nbsp;% System Independence
133 1 Marc Mengel
134 1 Marc Mengel
135 1 Marc Mengel
p<>. %(#14596)&nbsp;% The various flavors of UNIX
136 1 Marc Mengel
have many differences. You will generally have to release separate
137 1 Marc Mengel
instances of your (compiled) products for the different flavors.
138 1 Marc Mengel
However, the more you are able to insulate your product from
139 1 Marc Mengel
flavor/release dependencies, the easier your product will be to
140 1 Marc Mengel
maintain, and the less rigid it will appear to installers and
141 1 Marc Mengel
users.
142 1 Marc Mengel
143 1 Marc Mengel
144 1 Marc Mengel
h3.  %(#40738)&nbsp;% 16.1.3 Third-Party
145 1 Marc Mengel
Products Requiring a Hard-Coded Path
146 1 Marc Mengel
147 1 Marc Mengel
148 1 Marc Mengel
p<>. %(#40740)&nbsp;% If you're installing a
149 1 Marc Mengel
third-party product, downloaded from the Web or elsewhere, you may
150 1 Marc Mengel
not have the opportunity to code it such that it identifies its
151 1 Marc Mengel
location at run time based on ${UPS_PROD_DIR} or the
152 1 Marc Mengel
$<PRODUCT>_DIR environment variable. Whereas many products
153 1 Marc Mengel
never need to know their location (they only need to be in your
154 1 Marc Mengel
$PATH, for example), many other products %{font-weight: normal;color: #000000}do% need to know their location in order to locate auxiliary
155 1 Marc Mengel
commands, libraries, utilities, and so on.
156 1 Marc Mengel
157 1 Marc Mengel
158 1 Marc Mengel
h4.  %(#40741)&nbsp;% Techniques for
159 1 Marc Mengel
Implementing these Products
160 1 Marc Mengel
161 1 Marc Mengel
162 1 Marc Mengel
p<>. %(#40742)&nbsp;% There are two approaches to implement such products:
163 1 Marc Mengel
164 1 Marc Mengel
165 1 Marc Mengel
* For a product that is
166 1 Marc Mengel
already set up and which contains a script that requires an
167 1 Marc Mengel
interpreter, start the script with %{font-family: monospace}#!/usr/bin/env <interpreter>% (e.g., %{font-family: monospace}#!/usr/bin/env
168 1 Marc Mengel
perl% ). The %{font-weight: bold;color: #000000}env% program will run the first copy of the interpreter it
169 1 Marc Mengel
finds on your command search path, and your script is then
170 1 Marc Mengel
executable.
171 1 Marc Mengel
* Create a "wrapper" shell
172 1 Marc Mengel
script which sets up the %{font-weight: bold;color: #000000}UPS% environment, sets up your product, and then invokes the
173 1 Marc Mengel
appropriate commands.
174 1 Marc Mengel
175 1 Marc Mengel
176 1 Marc Mengel
h4.  %(#40763)&nbsp;% Examples of Products
177 1 Marc Mengel
Requiring Hard-coded Paths
178 1 Marc Mengel
179 1 Marc Mengel
180 1 Marc Mengel
p<>. %(#40764)&nbsp;% Here are examples of situations
181 1 Marc Mengel
in which hard-coded paths are unavoidable:
182 1 Marc Mengel
183 1 Marc Mengel
184 1 Marc Mengel
* Pre-built products which
185 1 Marc Mengel
have hard-coded paths.
186 1 Marc Mengel
* Products that you can
187 1 Marc Mengel
rebuild, but which were not coded with the idea of calculating
188 1 Marc Mengel
where the files sit at run time. You need to state where to
189 1 Marc Mengel
look for files at compile time, and this leads to hard-coded paths
190 1 Marc Mengel
in the images.
191 1 Marc Mengel
* Commands that are not
192 1 Marc Mengel
executed in the context of a shell, but rather as a program. You can't assume
193 1 Marc Mengel
the program running the command will expand environment variables. If you spell
194 1 Marc Mengel
out the whole path, you'll have to edit it every time a new version of
195 1 Marc Mengel
the command is released.
196 1 Marc Mengel
*  %{font-weight: bold;color: #000000}cgi% scripts, %{font-weight: bold;color: #000000}rsh% scripts and other situations in which you can't be sure
197 1 Marc Mengel
that the product will necessarily have been setup when it is called
198 1 Marc Mengel
by another one, and it needs to work anyway. Frequently you can create
199 1 Marc Mengel
product configuration scripts that copy or link the product files
200 1 Marc Mengel
into the correct location on the target node. In some cases for %{font-weight: bold;color: #000000}cgi% scripts, you can have your Web server setup the product
201 1 Marc Mengel
and pass the relevant environment variables.
202 1 Marc Mengel
203 1 Marc Mengel
204 1 Marc Mengel
h2.  %(#18733)&nbsp;% 16.2 Directory Structure
205 1 Marc Mengel
for a UPS Product Instance
206 1 Marc Mengel
207 1 Marc Mengel
208 1 Marc Mengel
p<>. %(#18735)&nbsp;% The top level directory of a %{font-weight: bold;color: #000000}UPS% product instance is called the %{font-weight: normal;color: #000000}product root directory% , and in general it should contain
209 1 Marc Mengel
files and subdirectories in which almost everything related to the
210 1 Marc Mengel
product instance resides: the executables, the library files, the
211 1 Marc Mengel
documentation, and so on. The %{font-family: monospace}ups% directory files (i.e., the %{font-weight: bold;color: #000000}UPS% metadata) and the table file usually reside here, but
212 1 Marc Mengel
are not required to do so.
213 1 Marc Mengel
214 1 Marc Mengel
p<>. %(#18736)&nbsp;%  %{font-weight: bold;color: #000000}UPS% is very lenient in the directory structure it allows. Nothing is
215 1 Marc Mengel
required in all situations beyond a product root directory.
216 1 Marc Mengel
Normally product instances have a table file containing actions
217 1 Marc Mengel
that are run during operations like product installation and
218 1 Marc Mengel
setup.
219 1 Marc Mengel
220 1 Marc Mengel
p<>. %(#18737)&nbsp;% We recommend that you follow a
221 1 Marc Mengel
few directory structure guidelines simply to conform to a generally
222 1 Marc Mengel
recognized format. This will make it easy for yourself and others
223 1 Marc Mengel
to identify each file and directory later on. The following is a
224 1 Marc Mengel
relatively complete sample directory structure underneath the
225 1 Marc Mengel
product root directory. Most products won't require all of these
226 1 Marc Mengel
elements. On the other hand, you may include other directories
227 1 Marc Mengel
and/or files not listed here.
228 1 Marc Mengel
 %{font-family: monospace}README% text file containing information such as origin of the product
229 1 Marc Mengel
(by whom, from where, etc.), support level, support group/person,
230 1 Marc Mengel
caveats and known bugs (may be contained in the %{font-family: monospace}ups% directory) %{font-family: monospace}bin% directory containing the executable(s) %{font-family: monospace}ups% directory containing metadata files and other executable and
231 1 Marc Mengel
data files used during implementation and invocation; may also
232 1 Marc Mengel
contain %{font-family: monospace}INSTALL_NOTE% (described below) file and the directories %{font-family: monospace}toman% , %{font-family: monospace}toInfo% , %{font-family: monospace}tonews% and %{font-family: monospace}tohtml% . Often the table file
233 1 Marc Mengel
resides here. (This directory is no longer a required element of a %{font-weight: bold;color: #000000}UPS% product.)Default location of the %{font-family: monospace}ups% directory is directly
234 1 Marc Mengel
underneath the product root, but it may reside anywhere. %{font-family: monospace}ups/INSTALL_NOTE% text file containing a detailed description of any installation
235 1 Marc Mengel
actions that are more easily performed directly by the installer
236 1 Marc Mengel
rather than by a script (beyond or instead of running %{font-family: monospace}configure% and/or %{font-family: monospace}current% ). This should not be a
237 1 Marc Mengel
script. This file is not usually needed. If provided, mention it in
238 1 Marc Mengel
the %{font-family: monospace}README% file so that
239 1 Marc Mengel
product installers know to run it. %{font-family: monospace}lib% directory containing libraries %{font-family: monospace}src% directory containing source code %{font-family: monospace}include% directory containing include files
240 1 Marc Mengel
p<>. %(#65671)&nbsp;% 
241 1 Marc Mengel
242 1 Marc Mengel
| [[upsv4TOC| !{width:84px;height:23px}images/navtoc.gif(TOC)!  ]] | [[partproddev| !{width:81px;height:23px}images/navprev.gif(PREV)!  ]] | [[develop| !{width:81px;height:23px}images/navnext.gif(NEXT)!  ]] |
243 1 Marc Mengel
244 1 Marc Mengel
245 1 Marc Mengel
p<>. **Last revised May 2014** 
246 1 Marc Mengel
247 1 Marc Mengel
| [[upsv4TOC| !{width:84px;height:23px}images/navtoc.gif(TOC)!  ]] | [[partproddev| !{width:81px;height:23px}images/navprev.gif(PREV)!  ]] | [[develop| !{width:81px;height:23px}images/navnext.gif(NEXT)!  ]] |
248 1 Marc Mengel
249 1 Marc Mengel
|.  !{width:60px;height:60px}images/CDlogo.gif(Fermilab CD logo)!  |\4. Complete Guide and Reference Manual for
250 1 Marc Mengel
UPS and UPD|
251 1 Marc Mengel
252 1 Marc Mengel
253 1 Marc Mengel
h3. Chapter Contents
254 1 Marc Mengel
255 1 Marc Mengel
256 1 Marc Mengel
p<>. [[dev_concepts#8346|Chapter 16: UPS Product Development: General
257 1 Marc Mengel
Considerations]] 
258 1 Marc Mengel
   [[dev_concepts#12914|16.1 Product Development
259 1 Marc Mengel
Considerations and Recommendations]] 
260 1 Marc Mengel
     [[dev_concepts#17335|16.1.1 All Products
261 1 Marc Mengel
(Locally Developed and Third Party)]] 
262 1 Marc Mengel
     [[dev_concepts#14504|16.1.2 Products that You
263 1 Marc Mengel
Develop]] 
264 1 Marc Mengel
     [[dev_concepts#40738|16.1.3 Third-Party
265 1 Marc Mengel
Products Requiring a Hard-Coded Path]] 
266 1 Marc Mengel
   [[dev_concepts#18733|16.2 Directory Structure for a UPS
267 1 Marc Mengel
Product Instance]] 
268 1 Marc Mengel
269 1 Marc Mengel
270 1 Marc Mengel
h1.  %(#8346)&nbsp;% Chapter 16: UPS Product
271 1 Marc Mengel
Development: General Considerations
272 1 Marc Mengel
273 1 Marc Mengel
274 1 Marc Mengel
p<>. %(#15554)&nbsp;% This chapter discusses the %{font-weight: bold;color: #000000}UPS% product development methodology and tools that can be
275 1 Marc Mengel
used in product development. It also provides recommendations for
276 1 Marc Mengel
organizing the local product development area and the individual
277 1 Marc Mengel
product root directories needed.
278 1 Marc Mengel
279 1 Marc Mengel
280 1 Marc Mengel
h2.  %(#12914)&nbsp;% 16.1 Product Development
281 1 Marc Mengel
Considerations and Recommendations
282 1 Marc Mengel
283 1 Marc Mengel
284 1 Marc Mengel
p<>. %(#13191)&nbsp;% This section provides
285 1 Marc Mengel
guidelines for product development as it affects the product's
286 1 Marc Mengel
inclusion in the %{font-weight: bold;color: #000000}UPS% framework.
287 1 Marc Mengel
288 1 Marc Mengel
p<>. %(#17303)&nbsp;% Simple scripts which run on any
289 1 Marc Mengel
architecture are straightforward to implement under %{font-weight: bold;color: #000000}UPS% . Products which are obtained from the outside world
290 1 Marc Mengel
(third party) as executable images with no source code are also
291 1 Marc Mengel
generally straightforward. The ones that get complicated are the
292 1 Marc Mengel
products which must be compiled and/or otherwise built for each and
293 1 Marc Mengel
every supported architecture.
294 1 Marc Mengel
295 1 Marc Mengel
296 1 Marc Mengel
h3.  %(#17335)&nbsp;% 16.1.1 All Products
297 1 Marc Mengel
(Locally Developed and Third Party)
298 1 Marc Mengel
299 1 Marc Mengel
300 1 Marc Mengel
h4.  %(#17317)&nbsp;% Shell Independence
301 1 Marc Mengel
302 1 Marc Mengel
303 1 Marc Mengel
p<>. %(#17331)&nbsp;% The product should run the same
304 1 Marc Mengel
way under both shell families, %{font-weight: bold;color: #000000}sh% and %{font-weight: bold;color: #000000}csh% . If the product requires any actions to take place
305 1 Marc Mengel
before it will run (e.g., its %{font-family: monospace}bin% directory added to $PATH, or
306 1 Marc Mengel
environment variables set), provide a table file containing
307 1 Marc Mengel
these actions. The %{font-weight: bold;color: #000000}UPS% environment is described in [[overview#8463|Chapter 2: %{font-weight: normal;color: #000000}Overview of UPS and UPD% ]] and table files in [[table_files#8463|Chapter 36: %{font-weight: normal;color: #000000}Table Files% ]] . The functions supported in table files are
308 1 Marc Mengel
designed to work in a shell-independent manner.
309 1 Marc Mengel
310 1 Marc Mengel
311 1 Marc Mengel
h4.  %(#17319)&nbsp;% Flavor Declaration in
312 1 Marc Mengel
UPS
313 1 Marc Mengel
314 1 Marc Mengel
315 1 Marc Mengel
p<>. %(#17332)&nbsp;% On your development system, we
316 1 Marc Mengel
recommend declaring products according to the %{font-weight: normal;color: #000000}fully specified flavor% of the machine on which
317 1 Marc Mengel
they were built. We consider this to be very
318 1 Marc Mengel
important, especially if the target systems contain or will ever
319 1 Marc Mengel
contain mixed OS releases (e.g., Linux+2.2 and Linux+2.5). This will
320 1 Marc Mengel
help to avoid problems when a new OS release doesn't run images
321 1 Marc Mengel
built on an older one, or vice-versa. It is difficult to go
322 1 Marc Mengel
back and try to figure out which OS release a particular product instance
323 1 Marc Mengel
was built for. It is better to be able to tell immediately from looking
324 1 Marc Mengel
at the database. Installers and users also need this information to
325 1 Marc Mengel
facilitate their database maintenance.
326 1 Marc Mengel
327 1 Marc Mengel
p<>. %(#17322)&nbsp;% Products which have no
328 1 Marc Mengel
flavor-dependence at all (shell scripts, for instance), should be
329 1 Marc Mengel
declared as NULL to the database (use the "zero" option, %{font-weight: bold;font-family: monospace}-0% ;
330 1 Marc Mengel
see [[options#8463|Chapter 25: %{font-weight: normal;color: #000000}Generic Command Option Descriptions% ]] ). For other
331 1 Marc Mengel
products, include the entire flavor string of the build platform in
332 1 Marc Mengel
the declaration, or the major portion of that string. For example,
333 1 Marc Mengel
if you build on an Linux machine running V2, declare your products
334 1 Marc Mengel
with the flavor Linux64bit+2 or Linux64bit+2.6 rather than just Linux64bit (e.g.,
335 1 Marc Mengel
use the flavor level corresponding to the options %{font-weight: bold;font-family: monospace}-4% or %{font-weight: bold;font-family: monospace}-3% or %{font-weight: bold;font-family: monospace}-2% rather than %{font-weight: bold;font-family: monospace}-1% )
336 1 Marc Mengel
337 1 Marc Mengel
338 1 Marc Mengel
h3.  %(#14504)&nbsp;% 16.1.2 Products that You
339 1 Marc Mengel
Develop
340 1 Marc Mengel
341 1 Marc Mengel
342 1 Marc Mengel
p<>. %(#14485)&nbsp;% If you're writing your own
343 1 Marc Mengel
product for implementation within %{font-weight: bold;color: #000000}UPS% , you have the luxury (and, we might add, the %{font-weight: normal;color: #000000}responsibility% ) of creating it such that it exploits the
344 1 Marc Mengel
important features of %{font-weight: bold;color: #000000}UPS% , thus making it easy for the user to install and run,
345 1 Marc Mengel
and easy for you or another developer to maintain in the future. We
346 1 Marc Mengel
urge you to follow the guidelines we present here.
347 1 Marc Mengel
348 1 Marc Mengel
349 1 Marc Mengel
h4.  %(#14508)&nbsp;% Self-Containment and
350 1 Marc Mengel
Location Determination
351 1 Marc Mengel
352 1 Marc Mengel
353 1 Marc Mengel
p<>. %(#14571)&nbsp;% First, design the product such
354 1 Marc Mengel
that it is self-contained. It should identify its location and the
355 1 Marc Mengel
location of any required files %{font-weight: normal;color: #000000}at run time% (as opposed to compile time). You as the product
356 1 Marc Mengel
developer have total control over the structure and contents of the
357 1 Marc Mengel
product root directory, but no control at all over where the
358 1 Marc Mengel
product root directory will reside on a target system.
359 1 Marc Mengel
360 1 Marc Mengel
p<>. %(#24638)&nbsp;%  !images/bombb.gif!  If
361 1 Marc Mengel
you write the product such that it calculates its location at
362 1 Marc Mengel
compile time, you'll be putting the hard-coded path to your
363 1 Marc Mengel
development environment into the image -- most likely %{font-weight: normal;color: #000000}not% the correct path on the user machine.
364 1 Marc Mengel
365 1 Marc Mengel
p<>. %(#19127)&nbsp;% 
366 1 Marc Mengel
367 1 Marc Mengel
368 1 Marc Mengel
h4.  %(#14507)&nbsp;% Reproducible Build
369 1 Marc Mengel
Procedure
370 1 Marc Mengel
371 1 Marc Mengel
372 1 Marc Mengel
p<>. %(#19464)&nbsp;% All products should be built
373 1 Marc Mengel
using a build script in order to ensure that the build procedure is
374 1 Marc Mengel
reproducible.
375 1 Marc Mengel
376 1 Marc Mengel
377 1 Marc Mengel
h4.  %(#14595)&nbsp;% System Independence
378 1 Marc Mengel
379 1 Marc Mengel
380 1 Marc Mengel
p<>. %(#14596)&nbsp;% The various flavors of UNIX
381 1 Marc Mengel
have many differences. You will generally have to release separate
382 1 Marc Mengel
instances of your (compiled) products for the different flavors.
383 1 Marc Mengel
However, the more you are able to insulate your product from
384 1 Marc Mengel
flavor/release dependencies, the easier your product will be to
385 1 Marc Mengel
maintain, and the less rigid it will appear to installers and
386 1 Marc Mengel
users.
387 1 Marc Mengel
388 1 Marc Mengel
389 1 Marc Mengel
h3.  %(#40738)&nbsp;% 16.1.3 Third-Party
390 1 Marc Mengel
Products Requiring a Hard-Coded Path
391 1 Marc Mengel
392 1 Marc Mengel
393 1 Marc Mengel
p<>. %(#40740)&nbsp;% If you're installing a
394 1 Marc Mengel
third-party product, downloaded from the Web or elsewhere, you may
395 1 Marc Mengel
not have the opportunity to code it such that it identifies its
396 1 Marc Mengel
location at run time based on ${UPS_PROD_DIR} or the
397 1 Marc Mengel
$<PRODUCT>_DIR environment variable. Whereas many products
398 1 Marc Mengel
never need to know their location (they only need to be in your
399 1 Marc Mengel
$PATH, for example), many other products %{font-weight: normal;color: #000000}do% need to know their location in order to locate auxiliary
400 1 Marc Mengel
commands, libraries, utilities, and so on.
401 1 Marc Mengel
402 1 Marc Mengel
403 1 Marc Mengel
h4.  %(#40741)&nbsp;% Techniques for
404 1 Marc Mengel
Implementing these Products
405 1 Marc Mengel
406 1 Marc Mengel
407 1 Marc Mengel
p<>. %(#40742)&nbsp;% There are two approaches to implement such products:
408 1 Marc Mengel
409 1 Marc Mengel
410 1 Marc Mengel
* For a product that is
411 1 Marc Mengel
already set up and which contains a script that requires an
412 1 Marc Mengel
interpreter, start the script with %{font-family: monospace}#!/usr/bin/env <interpreter>% (e.g., %{font-family: monospace}#!/usr/bin/env
413 1 Marc Mengel
perl% ). The %{font-weight: bold;color: #000000}env% program will run the first copy of the interpreter it
414 1 Marc Mengel
finds on your command search path, and your script is then
415 1 Marc Mengel
executable.
416 1 Marc Mengel
* Create a "wrapper" shell
417 1 Marc Mengel
script which sets up the %{font-weight: bold;color: #000000}UPS% environment, sets up your product, and then invokes the
418 1 Marc Mengel
appropriate commands.
419 1 Marc Mengel
420 1 Marc Mengel
421 1 Marc Mengel
h4.  %(#40763)&nbsp;% Examples of Products
422 1 Marc Mengel
Requiring Hard-coded Paths
423 1 Marc Mengel
424 1 Marc Mengel
425 1 Marc Mengel
p<>. %(#40764)&nbsp;% Here are examples of situations
426 1 Marc Mengel
in which hard-coded paths are unavoidable:
427 1 Marc Mengel
428 1 Marc Mengel
429 1 Marc Mengel
* Pre-built products which
430 1 Marc Mengel
have hard-coded paths.
431 1 Marc Mengel
* Products that you can
432 1 Marc Mengel
rebuild, but which were not coded with the idea of calculating
433 1 Marc Mengel
where the files sit at run time. You need to state where to
434 1 Marc Mengel
look for files at compile time, and this leads to hard-coded paths
435 1 Marc Mengel
in the images.
436 1 Marc Mengel
* Commands that are not
437 1 Marc Mengel
executed in the context of a shell, but rather as a program. You can't assume
438 1 Marc Mengel
the program running the command will expand environment variables. If you spell
439 1 Marc Mengel
out the whole path, you'll have to edit it every time a new version of
440 1 Marc Mengel
the command is released.
441 1 Marc Mengel
*  %{font-weight: bold;color: #000000}cgi% scripts, %{font-weight: bold;color: #000000}rsh% scripts and other situations in which you can't be sure
442 1 Marc Mengel
that the product will necessarily have been setup when it is called
443 1 Marc Mengel
by another one, and it needs to work anyway. Frequently you can create
444 1 Marc Mengel
product configuration scripts that copy or link the product files
445 1 Marc Mengel
into the correct location on the target node. In some cases for %{font-weight: bold;color: #000000}cgi% scripts, you can have your Web server setup the product
446 1 Marc Mengel
and pass the relevant environment variables.
447 1 Marc Mengel
448 1 Marc Mengel
449 1 Marc Mengel
h2.  %(#18733)&nbsp;% 16.2 Directory Structure
450 1 Marc Mengel
for a UPS Product Instance
451 1 Marc Mengel
452 1 Marc Mengel
453 1 Marc Mengel
p<>. %(#18735)&nbsp;% The top level directory of a %{font-weight: bold;color: #000000}UPS% product instance is called the %{font-weight: normal;color: #000000}product root directory% , and in general it should contain
454 1 Marc Mengel
files and subdirectories in which almost everything related to the
455 1 Marc Mengel
product instance resides: the executables, the library files, the
456 1 Marc Mengel
documentation, and so on. The %{font-family: monospace}ups% directory files (i.e., the %{font-weight: bold;color: #000000}UPS% metadata) and the table file usually reside here, but
457 1 Marc Mengel
are not required to do so.
458 1 Marc Mengel
459 1 Marc Mengel
p<>. %(#18736)&nbsp;%  %{font-weight: bold;color: #000000}UPS% is very lenient in the directory structure it allows. Nothing is
460 1 Marc Mengel
required in all situations beyond a product root directory.
461 1 Marc Mengel
Normally product instances have a table file containing actions
462 1 Marc Mengel
that are run during operations like product installation and
463 1 Marc Mengel
setup.
464 1 Marc Mengel
465 1 Marc Mengel
p<>. %(#18737)&nbsp;% We recommend that you follow a
466 1 Marc Mengel
few directory structure guidelines simply to conform to a generally
467 1 Marc Mengel
recognized format. This will make it easy for yourself and others
468 1 Marc Mengel
to identify each file and directory later on. The following is a
469 1 Marc Mengel
relatively complete sample directory structure underneath the
470 1 Marc Mengel
product root directory. Most products won't require all of these
471 1 Marc Mengel
elements. On the other hand, you may include other directories
472 1 Marc Mengel
and/or files not listed here.
473 1 Marc Mengel
 %{font-family: monospace}README% text file containing information such as origin of the product
474 1 Marc Mengel
(by whom, from where, etc.), support level, support group/person,
475 1 Marc Mengel
caveats and known bugs (may be contained in the %{font-family: monospace}ups% directory) %{font-family: monospace}bin% directory containing the executable(s) %{font-family: monospace}ups% directory containing metadata files and other executable and
476 1 Marc Mengel
data files used during implementation and invocation; may also
477 1 Marc Mengel
contain %{font-family: monospace}INSTALL_NOTE% (described below) file and the directories %{font-family: monospace}toman% , %{font-family: monospace}toInfo% , %{font-family: monospace}tonews% and %{font-family: monospace}tohtml% . Often the table file
478 1 Marc Mengel
resides here. (This directory is no longer a required element of a %{font-weight: bold;color: #000000}UPS% product.)Default location of the %{font-family: monospace}ups% directory is directly
479 1 Marc Mengel
underneath the product root, but it may reside anywhere. %{font-family: monospace}ups/INSTALL_NOTE% text file containing a detailed description of any installation
480 1 Marc Mengel
actions that are more easily performed directly by the installer
481 1 Marc Mengel
rather than by a script (beyond or instead of running %{font-family: monospace}configure% and/or %{font-family: monospace}current% ). This should not be a
482 1 Marc Mengel
script. This file is not usually needed. If provided, mention it in
483 1 Marc Mengel
the %{font-family: monospace}README% file so that
484 1 Marc Mengel
product installers know to run it. %{font-family: monospace}lib% directory containing libraries %{font-family: monospace}src% directory containing source code %{font-family: monospace}include% directory containing include files
485 1 Marc Mengel
p<>. %(#65671)&nbsp;% 
486 1 Marc Mengel
487 1 Marc Mengel
| [[upsv4TOC| !{width:84px;height:23px}images/navtoc.gif(TOC)!  ]] | [[partproddev| !{width:81px;height:23px}images/navprev.gif(PREV)!  ]] | [[develop| !{width:81px;height:23px}images/navnext.gif(NEXT)!  ]] |
488 1 Marc Mengel
489 1 Marc Mengel
490 1 Marc Mengel
p<>. **Last revised May 2014** 
491 1 Marc Mengel