1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Migration guides — Gentoo Python Guide documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
<link rel="stylesheet" type="text/css" href="_static/basic.css?v=c058f7c8" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=27fed22d" />
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="QA checks and warnings" href="qawarn.html" />
<link rel="prev" title="Porting tips" href="porting.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="migration-guides">
<h1>Migration guides<a class="headerlink" href="#migration-guides" title="Link to this heading">¶</a></h1>
<section id="migrating-from-old-python-usedep-syntax-in-python-single-r1">
<span id="index-0"></span><h2>Migrating from old PYTHON_USEDEP syntax in python-single-r1<a class="headerlink" href="#migrating-from-old-python-usedep-syntax-in-python-single-r1" title="Link to this heading">¶</a></h2>
<p>Prior to February 2020, <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> used to provide a single
<code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> variable alike the two other eclasses. However,
getting it to work correctly both on single-impl and multi-impl packages
required a gross hack.</p>
<p>The current eclass API requires using <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> function
to generate multi-impl deps instead, with <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> serving
as a placeholder. Single-impl deps can be expressed with
<code class="docutils literal notranslate"><span class="pre">PYTHON_SINGLE_USEDEP</span></code> that can be used either as placeholder,
or directly as a variable.</p>
<p>During a transitional period, <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> was banned entirely
and <code class="docutils literal notranslate"><span class="pre">PYTHON_MULTI_USEDEP</span></code> was used instead. As of EAPI 8,
the opposite is true — <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> is to be used,
and <code class="docutils literal notranslate"><span class="pre">PYTHON_MULTI_USEDEP</span></code> was removed.</p>
<p>The recommended rule of thumb for migrating old ebuilds is to:</p>
<ol class="arabic simple">
<li><p>Replace all instances of <code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> for simple-impl deps
with <code class="docutils literal notranslate"><span class="pre">${PYTHON_SINGLE_USEDEP}</span></code>. If you don’t know the type
of given dep, dependency check (repoman, pkgcheck) will tell you
if you chose wrong.</p></li>
<li><p>Wrap the dependencies using <code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> in a single
<code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> block (reordering may be desirable).</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">pkgcheck</span> <span class="pre">scan</span></code> or <code class="docutils literal notranslate"><span class="pre">repoman</span> <span class="pre">full</span></code>. If you get syntax errors,
you probably missed <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> or did not escape
the <code class="docutils literal notranslate"><span class="pre">$</span></code> in placeholder properly. If you get unmatched dependency,
you probably got single-impl vs. multi-impl wrong.</p></li>
</ol>
<p>This way, you can generally convert ebuilds using trial-and-error
method.</p>
</section>
<section id="migrating-from-eapi-7-to-eapi-8">
<span id="index-1"></span><h2>Migrating from EAPI 7 to EAPI 8<a class="headerlink" href="#migrating-from-eapi-7-to-eapi-8" title="Link to this heading">¶</a></h2>
<p>EAPI 8 has banned everything that’s been deprecated in EAPI 7, as well
as some other obsolete stuff. The following table lists all banned
things along with their suggested replacements.</p>
<blockquote>
<div><table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Deprecated thing</p></th>
<th class="head"><p>Replacement</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td colspan="2"><p>Private eclass API</p></td>
</tr>
<tr class="row-odd"><td><p>python_export</p></td>
<td><p>python_setup / getters</p></td>
</tr>
<tr class="row-even"><td><p>python_wrapper_setup</p></td>
<td><p>python_setup</p></td>
</tr>
<tr class="row-odd"><td colspan="2"><p>Obsolete API</p></td>
</tr>
<tr class="row-even"><td><p>distutils_install_for_testing
<code class="docutils literal notranslate"><span class="pre">--via-home</span></code></p></td>
<td><p>no argument (<code class="docutils literal notranslate"><span class="pre">--via-root</span></code>)
or <code class="docutils literal notranslate"><span class="pre">--via-venv</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>python_gen_usedep</p></td>
<td><p>python_gen_cond_dep</p></td>
</tr>
<tr class="row-even"><td><p>PYTHON_MULTI_USEDEP</p></td>
<td><p>PYTHON_USEDEP</p></td>
</tr>
<tr class="row-odd"><td colspan="2"><p>mydistutilsargs rename</p></td>
</tr>
<tr class="row-even"><td><p>mydistutilsargs</p></td>
<td><p>DISTUTILS_ARGS</p></td>
</tr>
<tr class="row-odd"><td colspan="2"><p>Post-Python 2 cleanup</p></td>
</tr>
<tr class="row-even"><td><p>python_gen* -2 / python2
/ pypy</p></td>
<td><p>remove entirely</p></td>
</tr>
<tr class="row-odd"><td><p>python_gen* -3</p></td>
<td><p>make unconditional</p></td>
</tr>
<tr class="row-even"><td><p>python_is_python3</p></td>
<td><p>always assume true</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>The changes can be split roughly into four groups: ban of now-private
eclass API, ban of obsolete API functions, mydistutilsargs rename
and bans related to post-Python 2 cleanup.</p>
<p>The private eclass API part involves <code class="docutils literal notranslate"><span class="pre">python_export</span></code>
and <code class="docutils literal notranslate"><span class="pre">python_wrapper_setup</span></code>. Both were deprecated in March 2020,
and they were never covered in this guide. The former was historically
used to get information about the Python interpreter (either the current
<code class="docutils literal notranslate"><span class="pre">${EPYTHON}</span></code> or an arbitrary choice), the latter to create the wrapper
directory containing <code class="docutils literal notranslate"><span class="pre">python</span></code> and other executables.</p>
<p>When the functions were used to establish a Python build environment,
the replacement for both is a single <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> call. When
<code class="docutils literal notranslate"><span class="pre">python_export</span></code> was used to grab additional details about the Python
interpreter, the various <code class="docutils literal notranslate"><span class="pre">python_get*</span></code> functions should be used
instead.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>src_configure<span class="o">()</span><span class="w"> </span><span class="o">{</span>
<span class="w"> </span><span class="c1"># ...</span>
<span class="w"> </span><span class="c1"># OLD:</span>
<span class="w"> </span><span class="nb">local</span><span class="w"> </span>PYTHON_INCLUDEDIR<span class="w"> </span>PYTHON_LIBPATH
<span class="w"> </span>python_export<span class="w"> </span>PYTHON_INCLUDEDIR<span class="w"> </span>PYTHON_LIBPATH
<span class="w"> </span><span class="nv">mycmakeargs</span><span class="o">+=(</span>
<span class="w"> </span>-DPython3_INCLUDE_DIR<span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_INCLUDEDIR</span><span class="si">}</span><span class="s2">"</span>
<span class="w"> </span>-DPython3_LIBRARY<span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_LIBPATH</span><span class="si">}</span><span class="s2">"</span>
<span class="w"> </span><span class="o">)</span>
<span class="w"> </span><span class="c1"># NEW:</span>
<span class="w"> </span><span class="nv">mycmakeargs</span><span class="o">+=(</span>
<span class="w"> </span>-DPython3_INCLUDE_DIR<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_includedir<span class="k">)</span><span class="s2">"</span>
<span class="w"> </span>-DPython3_LIBRARY<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_library_path<span class="k">)</span><span class="s2">"</span>
<span class="w"> </span><span class="o">)</span>
<span class="o">}</span>
</pre></div>
</div>
<p>The second group involves sundry API that were deprecated earlier.
These are:</p>
<ol class="arabic simple">
<li><p><code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span> <span class="pre">--via-home</span></code> layout that stopped
working correctly at some point. The default <code class="docutils literal notranslate"><span class="pre">--via-root</span></code> should
work most of the time, and <code class="docutils literal notranslate"><span class="pre">-via-venv</span></code> replace the remaining cases
for the removed layout.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">python_gen_usedep</span></code> function that was historically used to generate
partial USE dependencies, and was generally combined with
<code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code> to force specific (usually old) Python interpreters
for specific features. This was really ugly. Nowadays, you should
really use <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> instead.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MULTI_USEDEP</span></code> placeholder that was temporarily used
in python-single-r1 ebuilds. <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> is equivalent now.</p></li>
</ol>
<p>The third group is a sole rename of <code class="docutils literal notranslate"><span class="pre">mydistutilsargs</span></code> variable.
Since you usually need to pass the same arguments in all phase
functions, this variable was not really used in local scope. It has
been renamed to uppercase <code class="docutils literal notranslate"><span class="pre">DISTUTILS_ARGS</span></code> to follow the common
pattern for global scope variables.</p>
<p>Finally, the fourth group involves banning some of the features that
were specifically used in order to support distinguish between Python 2
and Python 3. This is meant to force cleaning up old cruft from
ebuilds. It comes in three parts:</p>
<ol class="arabic simple">
<li><p>Banning arguments to <code class="docutils literal notranslate"><span class="pre">python_gen*</span></code> that reference Python 2
(e.g. <code class="docutils literal notranslate"><span class="pre">-2</span></code>, <code class="docutils literal notranslate"><span class="pre">python2*</span></code>, <code class="docutils literal notranslate"><span class="pre">python2_7</span></code>, <code class="docutils literal notranslate"><span class="pre">pypy</span></code>). Since Python 2
is no longer supported in the relevant code paths, the relevant calls
should just be removed.</p></li>
<li><p>Banning the <code class="docutils literal notranslate"><span class="pre">-3</span></code> short-hand to <code class="docutils literal notranslate"><span class="pre">python_gen*</span></code>. Since all
supported interpreters are compatible with Python 3 now, the relevant
code should be made unconditional. Note that <code class="docutils literal notranslate"><span class="pre">python3*</span></code> is still
useful, as it distinguishes CPython from PyPy3.</p></li>
<li><p>Banning the <code class="docutils literal notranslate"><span class="pre">python_is_python3</span></code> function. Since the removal
of Python 2 support, it always evaluated to true.</p></li>
</ol>
<p>All the aforementioned replacements are available in all EAPIs.</p>
</section>
<section id="migrating-to-pep-517-builds">
<h2>Migrating to PEP 517 builds<a class="headerlink" href="#migrating-to-pep-517-builds" title="Link to this heading">¶</a></h2>
<p>As of January 2022, the <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> can use PEP 517 build backends
instead of calling setuptools directly. The new mode is particularly
useful for:</p>
<ul class="simple">
<li><p>packages using flit and poetry, as a better replacement for
the deprecated <code class="docutils literal notranslate"><span class="pre">dev-python/pyproject2setuppy</span></code> hack</p></li>
<li><p>packages using other PEP 517 build systems (such as pdm) that are not
supported in legacy mode at all</p></li>
<li><p>packages using setuptools without <code class="docutils literal notranslate"><span class="pre">setup.py</span></code></p></li>
<li><p>packages using plain distutils, as the mode handles the switch from
deprecated stdlib distutils to the version vendored in setuptools
safely</p></li>
</ul>
<p>The PEP 517 mode provides the test phase with venv-style installed
package tree (alike <code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span> <span class="pre">--via-venv</span></code>)
that should make testing more streamlined.</p>
<p>Unfortunately, the new mode can cause issues with customized distutils
and setuptools build systems. It is important to verify the installed
file list after the migration. Packages that require custom configure
phases or passing arguments are not supported at the moment.</p>
<p>For simple packages, the migration consists of:</p>
<ol class="arabic simple">
<li><p>Adding <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_PEP517</span></code> above the inherit line. The value
indicates the build system used, e.g. <code class="docutils literal notranslate"><span class="pre">flit</span></code>, <code class="docutils literal notranslate"><span class="pre">poetry</span></code>,
<code class="docutils literal notranslate"><span class="pre">setuptools</span></code> (used also for distutils).</p></li>
<li><p>Removing <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS</span></code>. If the previous value was
<code class="docutils literal notranslate"><span class="pre">rdepend</span></code> (and indeed a runtime dependency is required), then
<code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code> needs to be explicitly added to
<code class="docutils literal notranslate"><span class="pre">RDEPEND</span></code>.</p></li>
<li><p>Removing <code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span></code> and/or <code class="docutils literal notranslate"><span class="pre">--install</span></code>
option to <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code>. This should no longer be
necessary and tests should work out of the box.</p></li>
</ol>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1>
<search id="searchbox" style="display: none" role="search">
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li>
<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li>
<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li>
<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li>
<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li>
<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li>
<li class="toctree-l1"><a class="reference internal" href="test.html">Tests in Python packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="pypi.html">pypi — helper eclass for PyPI archives</a></li>
<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li>
<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li>
<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li>
<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Migration guides</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#migrating-from-old-python-usedep-syntax-in-python-single-r1">Migrating from old PYTHON_USEDEP syntax in python-single-r1</a></li>
<li class="toctree-l2"><a class="reference internal" href="#migrating-from-eapi-7-to-eapi-8">Migrating from EAPI 7 to EAPI 8</a></li>
<li class="toctree-l2"><a class="reference internal" href="#migrating-to-pep-517-builds">Migrating to PEP 517 builds</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="qawarn.html">QA checks and warnings</a></li>
<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li>
<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="porting.html" title="previous chapter">Porting tips</a></li>
<li>Next: <a href="qawarn.html" title="next chapter">QA checks and warnings</a></li>
</ul></li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2020, Michał Górny, license: CC BY 4.0.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.0.2</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
|
<a href="_sources/migration.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|
GitWeb