[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / dist / postinstallation-script.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="dist.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="dist.html" title='Distributing Python Modules' />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="creating-rpms.html" />
<link rel="parent" href="built-dist.html" />
<link rel="next" href="package-index.html" />
<meta name='aesop' content='information' />
<title>5.3 Creating Windows Installers</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.2 Creating RPM packages"
  href="creating-rpms.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5. Creating Built Distributions"
  href="built-dist.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6. Registering with the"
  href="package-index.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Distributing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="creating-rpms.html">5.2 Creating RPM packages</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="built-dist.html">5. Creating Built Distributions</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="package-index.html">6. Registering with the</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="postinstallation-script.html#SECTION005310000000000000000">5.3.1 The Postinstallation script</a>
</ul>
<!--End of Table of Child-Links-->
</div>
<HR>

<H1><A NAME="SECTION005300000000000000000"></A>
<A NAME="creating-wininst"></A>
<BR>
5.3 Creating Windows Installers
</H1>

<P>
Executable installers are the natural format for binary distributions
on Windows.  They display a nice graphical user interface, display
some information about the module distribution to be installed taken
from the metadata in the setup script, let the user select a few
options, and start or cancel the installation.

<P>
Since the metadata is taken from the setup script, creating Windows
installers is usually as easy as running:

<P>
<div class="verbatim"><pre>
python setup.py bdist_wininst
</pre></div>

<P>
or the <code class="du-command">bdist</code> command with the <b class="programopt">--formats</b> option:

<P>
<div class="verbatim"><pre>
python setup.py bdist --formats=wininst
</pre></div>

<P>
If you have a pure module distribution (only containing pure Python
modules and packages), the resulting installer will be version
independent and have a name like <span class="file">foo-1.0.win32.exe</span>.  These
installers can even be created on <span class="Unix">Unix</span> or Mac OS platforms.

<P>
If you have a non-pure distribution, the extensions can only be
created on a Windows platform, and will be Python version dependent.
The installer filename will reflect this and now has the form
<span class="file">foo-1.0.win32-py2.0.exe</span>.  You have to create a separate installer
for every Python version you want to support.

<P>
The installer will try to compile pure modules into bytecode after
installation on the target system in normal and optimizing mode.  If
you don't want this to happen for some reason, you can run the
<code class="du-command">bdist_wininst</code> command with the
<b class="programopt">--no-target-compile</b> and/or the
<b class="programopt">--no-target-optimize</b> option.

<P>
By default the installer will display the cool ``Python Powered'' logo
when it is run, but you can also supply your own bitmap which must be
a Windows <span class="file">.bmp</span> file with the <b class="programopt">--bitmap</b> option.

<P>
The installer will also display a large title on the desktop
background window when it is run, which is constructed from the name
of your distribution and the version number.  This can be changed to
another text by using the <b class="programopt">--title</b> option.

<P>
The installer file will be written to the ``distribution directory''
-- normally <span class="file">dist/</span>, but customizable with the
<b class="programopt">--dist-dir</b> option.

<P>

<H2><A NAME="SECTION005310000000000000000"></A>
<A NAME="postinstallation-script"></A>
<BR>
5.3.1 The Postinstallation script
</H2>

<P>
Starting with Python 2.3, a postinstallation script can be specified
which the <b class="programopt">--install-script</b> option.  The basename of the
script must be specified, and the script filename must also be listed
in the scripts argument to the setup function.

<P>
This script will be run at installation time on the target system
after all the files have been copied, with <code>argv[1]</code> set to
<b class="programopt">-install</b>, and again at uninstallation time before the
files are removed with <code>argv[1]</code> set to <b class="programopt">-remove</b>.

<P>
The installation script runs embedded in the windows installer, every
output (<code>sys.stdout</code>, <code>sys.stderr</code>) is redirected into a
buffer and will be displayed in the GUI after the script has finished.

<P>
Some functions especially useful in this context are available as
additional built-in functions in the installation script.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1' xml:id='l2h-1' class="function">directory_created</tt></b>(</nobr></td>
  <td><var>path</var>)</td></tr></table></dt>
<dd>
<dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt class="function">file_created</tt></b>(</nobr></td>
  <td><var>path</var>)</td></tr></table></dt>
<dd>  These functions should be called when a directory or file is created
  by the postinstall script at installation time.  It will register
  <var>path</var> with the uninstaller, so that it will be removed when the
  distribution is uninstalled.  To be safe, directories are only removed
  if they are empty.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3' xml:id='l2h-3' class="function">get_special_folder_path</tt></b>(</nobr></td>
  <td><var>csidl_string</var>)</td></tr></table></dt>
<dd>
  This function can be used to retrieve special folder locations on
  Windows like the Start Menu or the Desktop.  It returns the full
  path to the folder.  <var>csidl_string</var> must be one of the following
  strings:

<P>
<div class="verbatim"><pre>
"CSIDL_APPDATA"

"CSIDL_COMMON_STARTMENU"
"CSIDL_STARTMENU"

"CSIDL_COMMON_DESKTOPDIRECTORY"
"CSIDL_DESKTOPDIRECTORY"

"CSIDL_COMMON_STARTUP"
"CSIDL_STARTUP"

"CSIDL_COMMON_PROGRAMS"
"CSIDL_PROGRAMS"

"CSIDL_FONTS"
</pre></div>

<P>
If the folder cannot be retrieved, <tt class="exception">OSError</tt> is raised.

<P>
Which folders are available depends on the exact Windows version,
  and probably also the configuration.  For details refer to
  Microsoft's documentation of the
  <tt class="cfunction">SHGetSpecialFolderPath()</tt> function.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4' xml:id='l2h-4' class="function">create_shortcut</tt></b>(</nobr></td>
  <td><var>target, description,
                                  filename</var><big>[</big><var>,
                                  arguments</var><big>[</big><var>,
                                  workdir</var><big>[</big><var>,
                                  iconpath</var><big>[</big><var>, iconindex</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  This function creates a shortcut.
  <var>target</var> is the path to the program to be started by the shortcut.
  <var>description</var> is the description of the shortcut.
  <var>filename</var> is the title of the shortcut that the user will see.
  <var>arguments</var> specifies the command line arguments, if any.
  <var>workdir</var> is the working directory for the program.
  <var>iconpath</var> is the file containing the icon for the shortcut,
  and <var>iconindex</var> is the index of the icon in the file
  <var>iconpath</var>.  Again, for details consult the Microsoft
  documentation for the <tt class="class">IShellLink</tt> interface.
</dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.2 Creating RPM packages"
  href="creating-rpms.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5. Creating Built Distributions"
  href="built-dist.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6. Registering with the"
  href="package-index.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Distributing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="creating-rpms.html">5.2 Creating RPM packages</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="built-dist.html">5. Creating Built Distributions</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="package-index.html">6. Registering with the</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="dist.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="dist.html" title='Distributing Python Modules' />
	8	<link rel='index' href='genindex.html' title='Index' />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="prev" href="creating-rpms.html" />
	12	<link rel="parent" href="built-dist.html" />
	13	<link rel="next" href="package-index.html" />
	14	<meta name='aesop' content='information' />
	15	<title>5.3 Creating Windows Installers</title>
	16	</head>
	17	<body>
	18	<DIV CLASS="navigation">
	19	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	20	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	21	<tr>
	22	<td class='online-navigation'><a rel="prev" title="5.2 Creating RPM packages"
	23	href="creating-rpms.html"><img src='../icons/previous.png'
	24	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	25	<td class='online-navigation'><a rel="parent" title="5. Creating Built Distributions"
	26	href="built-dist.html"><img src='../icons/up.png'
	27	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	28	<td class='online-navigation'><a rel="next" title="6. Registering with the"
	29	href="package-index.html"><img src='../icons/next.png'
	30	border='0' height='32' alt='Next Page' width='32' /></A></td>
	31	<td align="center" width="100%">Distributing Python Modules</td>
	32	<td class='online-navigation'><img src='../icons/blank.png'
	33	border='0' height='32' alt='' width='32' /></td>
	34	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	35	border='0' height='32' alt='Module Index' width='32' /></a></td>
	36	<td class='online-navigation'><a rel="index" title="Index"
	37	href="genindex.html"><img src='../icons/index.png'
	38	border='0' height='32' alt='Index' width='32' /></A></td>
	39	</tr></table>
	40	<div class='online-navigation'>
	41	<b class="navlabel">Previous:</b>
	42	<a class="sectref" rel="prev" href="creating-rpms.html">5.2 Creating RPM packages</A>
	43	<b class="navlabel">Up:</b>
	44	<a class="sectref" rel="parent" href="built-dist.html">5. Creating Built Distributions</A>
	45	<b class="navlabel">Next:</b>
	46	<a class="sectref" rel="next" href="package-index.html">6. Registering with the</A>
	47	</div>
	48	<hr /></div>
	49	</DIV>
	50	<!--End of Navigation Panel-->
	51	<div class='online-navigation'>
	52	<!--Table of Child-Links-->
	53	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
	54
	55	<UL CLASS="ChildLinks">
	56	<LI><A href="postinstallation-script.html#SECTION005310000000000000000">5.3.1 The Postinstallation script</a>
	57	</ul>
	58	<!--End of Table of Child-Links-->
	59	</div>
	60	<HR>
	61
	62	<H1><A NAME="SECTION005300000000000000000"></A>
	63	<A NAME="creating-wininst"></A>
	64	<BR>
65	5.3 Creating Windows Installers
66	</H1>
67
68	<P>
69	Executable installers are the natural format for binary distributions
70	on Windows. They display a nice graphical user interface, display
71	some information about the module distribution to be installed taken
72	from the metadata in the setup script, let the user select a few
73	options, and start or cancel the installation.
74
75	<P>
76	Since the metadata is taken from the setup script, creating Windows
77	installers is usually as easy as running:
78
79	<P>
80	<div class="verbatim"><pre>
81	python setup.py bdist_wininst
82	</pre></div>
83
84	<P>
85	or the <code class="du-command">bdist</code> command with the <b class="programopt">--formats</b> option:
86
87	<P>
88	<div class="verbatim"><pre>
89	python setup.py bdist --formats=wininst
90	</pre></div>
91
92	<P>
93	If you have a pure module distribution (only containing pure Python
94	modules and packages), the resulting installer will be version
95	independent and have a name like <span class="file">foo-1.0.win32.exe</span>. These
96	installers can even be created on <span class="Unix">Unix</span> or Mac OS platforms.
97
98	<P>
99	If you have a non-pure distribution, the extensions can only be
100	created on a Windows platform, and will be Python version dependent.
101	The installer filename will reflect this and now has the form
102	<span class="file">foo-1.0.win32-py2.0.exe</span>. You have to create a separate installer
103	for every Python version you want to support.
104
105	<P>
106	The installer will try to compile pure modules into bytecode after
107	installation on the target system in normal and optimizing mode. If
108	you don't want this to happen for some reason, you can run the
109	<code class="du-command">bdist_wininst</code> command with the
110	<b class="programopt">--no-target-compile</b> and/or the
111	<b class="programopt">--no-target-optimize</b> option.
112
113	<P>
114	By default the installer will display the cool ``Python Powered'' logo
115	when it is run, but you can also supply your own bitmap which must be
116	a Windows <span class="file">.bmp</span> file with the <b class="programopt">--bitmap</b> option.
117
118	<P>
119	The installer will also display a large title on the desktop
120	background window when it is run, which is constructed from the name
121	of your distribution and the version number. This can be changed to
122	another text by using the <b class="programopt">--title</b> option.
123
124	<P>
125	The installer file will be written to the ``distribution directory''
126	-- normally <span class="file">dist/</span>, but customizable with the
127	<b class="programopt">--dist-dir</b> option.
128
129	<P>
130
131	<H2><A NAME="SECTION005310000000000000000"></A>
132	<A NAME="postinstallation-script"></A>
133	<BR>
134	5.3.1 The Postinstallation script
135	</H2>
136
137	<P>
138	Starting with Python 2.3, a postinstallation script can be specified
139	which the <b class="programopt">--install-script</b> option. The basename of the
140	script must be specified, and the script filename must also be listed
141	in the scripts argument to the setup function.
142
143	<P>
144	This script will be run at installation time on the target system
145	after all the files have been copied, with <code>argv[1]</code> set to
146	<b class="programopt">-install</b>, and again at uninstallation time before the
147	files are removed with <code>argv[1]</code> set to <b class="programopt">-remove</b>.
148
149	<P>
150	The installation script runs embedded in the windows installer, every
151	output (<code>sys.stdout</code>, <code>sys.stderr</code>) is redirected into a
152	buffer and will be displayed in the GUI after the script has finished.
153
154	<P>
155	Some functions especially useful in this context are available as
156	additional built-in functions in the installation script.
157
158	<P>
159	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
160	<td><nobr><b><tt id='l2h-1' xml:id='l2h-1' class="function">directory_created</tt></b>(</nobr></td>
161	<td><var>path</var>)</td></tr></table></dt>
162	<dd>
163	<dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
164	<td><nobr><b><tt class="function">file_created</tt></b>(</nobr></td>
165	<td><var>path</var>)</td></tr></table></dt>
166	<dd> These functions should be called when a directory or file is created
167	by the postinstall script at installation time. It will register
168	<var>path</var> with the uninstaller, so that it will be removed when the
169	distribution is uninstalled. To be safe, directories are only removed
170	if they are empty.
171	</dl>
172
173	<P>
174	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
175	<td><nobr><b><tt id='l2h-3' xml:id='l2h-3' class="function">get_special_folder_path</tt></b>(</nobr></td>
176	<td><var>csidl_string</var>)</td></tr></table></dt>
177	<dd>
178	This function can be used to retrieve special folder locations on
179	Windows like the Start Menu or the Desktop. It returns the full
180	path to the folder. <var>csidl_string</var> must be one of the following
181	strings:
182
183	<P>
184	<div class="verbatim"><pre>
185	"CSIDL_APPDATA"
186
187	"CSIDL_COMMON_STARTMENU"
188	"CSIDL_STARTMENU"
189
190	"CSIDL_COMMON_DESKTOPDIRECTORY"
191	"CSIDL_DESKTOPDIRECTORY"
192
193	"CSIDL_COMMON_STARTUP"
194	"CSIDL_STARTUP"
195
196	"CSIDL_COMMON_PROGRAMS"
197	"CSIDL_PROGRAMS"
198
199	"CSIDL_FONTS"
200	</pre></div>
201
202	<P>
203	If the folder cannot be retrieved, <tt class="exception">OSError</tt> is raised.
204
205	<P>
206	Which folders are available depends on the exact Windows version,
207	and probably also the configuration. For details refer to
208	Microsoft's documentation of the
209	<tt class="cfunction">SHGetSpecialFolderPath()</tt> function.
210	</dl>
211
212	<P>
213	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
214	<td><nobr><b><tt id='l2h-4' xml:id='l2h-4' class="function">create_shortcut</tt></b>(</nobr></td>
215	<td><var>target, description,
216	filename</var><big>[</big><var>,
217	arguments</var><big>[</big><var>,
218	workdir</var><big>[</big><var>,
219	iconpath</var><big>[</big><var>, iconindex</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
220	<dd>
221	This function creates a shortcut.
222	<var>target</var> is the path to the program to be started by the shortcut.
223	<var>description</var> is the description of the shortcut.
224	<var>filename</var> is the title of the shortcut that the user will see.
225	<var>arguments</var> specifies the command line arguments, if any.
226	<var>workdir</var> is the working directory for the program.
227	<var>iconpath</var> is the file containing the icon for the shortcut,
228	and <var>iconindex</var> is the index of the icon in the file
229	<var>iconpath</var>. Again, for details consult the Microsoft
230	documentation for the <tt class="class">IShellLink</tt> interface.
231	</dl>
232
233	<P>
234
235	<DIV CLASS="navigation">
236	<div class='online-navigation'>
237	<p></p><hr />
238	<table align="center" width="100%" cellpadding="0" cellspacing="2">
239	<tr>
240	<td class='online-navigation'><a rel="prev" title="5.2 Creating RPM packages"
241	href="creating-rpms.html"><img src='../icons/previous.png'
242	border='0' height='32' alt='Previous Page' width='32' /></A></td>
243	<td class='online-navigation'><a rel="parent" title="5. Creating Built Distributions"
244	href="built-dist.html"><img src='../icons/up.png'
245	border='0' height='32' alt='Up One Level' width='32' /></A></td>
246	<td class='online-navigation'><a rel="next" title="6. Registering with the"
247	href="package-index.html"><img src='../icons/next.png'
248	border='0' height='32' alt='Next Page' width='32' /></A></td>
249	<td align="center" width="100%">Distributing Python Modules</td>
250	<td class='online-navigation'><img src='../icons/blank.png'
251	border='0' height='32' alt='' width='32' /></td>
252	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
253	border='0' height='32' alt='Module Index' width='32' /></a></td>
254	<td class='online-navigation'><a rel="index" title="Index"
255	href="genindex.html"><img src='../icons/index.png'
256	border='0' height='32' alt='Index' width='32' /></A></td>
257	</tr></table>
258	<div class='online-navigation'>
259	<b class="navlabel">Previous:</b>
260	<a class="sectref" rel="prev" href="creating-rpms.html">5.2 Creating RPM packages</A>
261	<b class="navlabel">Up:</b>
262	<a class="sectref" rel="parent" href="built-dist.html">5. Creating Built Distributions</A>
263	<b class="navlabel">Next:</b>
264	<a class="sectref" rel="next" href="package-index.html">6. Registering with the</A>
265	</div>
266	</div>
267	<hr />
268	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
269	</DIV>
270	<!--End of Navigation Panel-->
271	<ADDRESS>
272	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
273	</ADDRESS>
274	</BODY>
275	</HTML>