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
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Choosing between Python eclasses — Gentoo Python Guide documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Common basics" href="basic.html" />
<link rel="prev" title="Python interpreters" href="interpreter.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="choosing-between-python-eclasses">
<h1>Choosing between Python eclasses<a class="headerlink" href="#choosing-between-python-eclasses" title="Permalink to this headline">¶</a></h1>
<section id="build-time-vs-runtime-use">
<h2>Build-time vs runtime use<a class="headerlink" href="#build-time-vs-runtime-use" title="Permalink to this headline">¶</a></h2>
<p>The first basis for choosing Python eclass is whether Python is used
merely at build-time or at runtime as well.</p>
<p>A runtime use occurs if the package explicitly needs Python to be
installed along with it, in order for it to function correctly. This
generally happens if the package installs Python modules, extensions,
scripts, or executables calling the Python interpreter or linking
to libpython. This also applies to bash scripts or other executables
that call python inline.</p>
<p>A build-time use occurs if the package calls the Python interpreter
or any kind of aforementioned executables during package’s build
(or install) phases.</p>
<p>If the package uses Python purely at build-time, the <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code>
eclass is appropriate. Otherwise, <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>, <code class="docutils literal notranslate"><span class="pre">python-r1</span></code>
or their derivatives are to be used.</p>
<p>A specific exception to that rule is when the package is only calling
external Python scripts directly (i.e. not via <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">/usr/bin/foo</span></code>).
If the called executables can be considered fully contained
dependency-wise, there is no need to use an eclass.</p>
<p>For example, when using <code class="docutils literal notranslate"><span class="pre">dev-util/meson</span></code> to build a package, there is
no need to use a Python eclass since Meson abstracts away its Pythonic
implementation details and works as a regular executable for your
packages. However, <code class="docutils literal notranslate"><span class="pre">dev-util/scons</span></code> requires Python eclass since it
loads Python code from the package and a compatible Python version must
be enforced.</p>
</section>
<section id="single-impl-vs-multi-impl">
<h2>Single-impl vs multi-impl<a class="headerlink" href="#single-impl-vs-multi-impl" title="Permalink to this headline">¶</a></h2>
<p>The second important basis for packages using Python at runtime is
whether the package in question should support multi-implementation
install or not.</p>
<p>A <em>single-impl</em> package is a package requiring the user to choose
exactly one Python implementation to be built against. This means
that the scripts installed by that package will be run via specified
Python interpreter, and that the modules and extensions will be
importable from it only. The package’s Python reverse dependencies will
also have to use the same implementation. Since the package can’t
support having more than one implementation enabled, its reverse
dependencies have to be simple-impl as well.</p>
<p>Single-impl packages use <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> eclass. Writing ebuilds
for them is easier since it is generally sufficient to call setup
function early on, and the upstream build system generally takes care
of using selected Python version correctly. Making packages single-impl
is recommended when dealing with packages that are not purely written
for Python or have single-impl dependencies.</p>
<p>A <em>multi-impl</em> package allows user to enable multiple (preferably
any number of) implementations. The modules, extensions and scripts
installed by the package are installed separately for each enabled
implementation, and can therefore be used from any of them. The package
can have reverse dependencies enabling only a subset of its
implementations.</p>
<p>Multi-impl packages use <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> eclass. Ebuilds are more complex
since they need to explicitly repeat build and install steps for each
enabled implementation. Using this model is recommended for packages
providing Python modules or extensions only, or having multi-impl
reverse dependencies. In some cases supporting multi-impl build
requires applying hacks, e.g. <code class="docutils literal notranslate"><span class="pre">dev-libs/boost[python]</span></code> uses
non-standard names to install <code class="docutils literal notranslate"><span class="pre">libboost_python</span></code> for multiple Python
versions.</p>
<p>The implementation for single-impl packages is selected
via <code class="docutils literal notranslate"><span class="pre">PYTHON_SINGLE_TARGET</span></code>, while multi-impl uses <code class="docutils literal notranslate"><span class="pre">PYTHON_TARGETS</span></code>.
These USE flag sets can be set independently to provide greater
flexibility for developers and end users.</p>
</section>
<section id="distutils-and-related-build-systems">
<h2>Distutils and related build systems<a class="headerlink" href="#distutils-and-related-build-systems" title="Permalink to this headline">¶</a></h2>
<p>The third basis for choosing an eclass is the build system used.
If the project uses one of Python-specific build systems, that is
distutils, setuptools, flit or poetry, the <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> eclass
should be used instead of the other eclasses. As a rule of thumb,
this happens when either <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> or <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file exists
in the distribution.</p>
<p><code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> builds on either <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> or <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>,
therefore it can be used to create both multi-impl and single-impl
packages. It provides full set of default phase functions, making
writing ebuilds much easier.</p>
</section>
<section id="a-rule-of-thumb">
<h2>A rule of thumb<a class="headerlink" href="#a-rule-of-thumb" title="Permalink to this headline">¶</a></h2>
<p>As a rule of thumb, the following checklist can be used to determine
the eclass to use:</p>
<ol class="arabic simple">
<li><p>If the package has <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> or <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file,
use <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code>.</p></li>
<li><p>If the package primarily installs Python modules or extensions
or has multi-impl reverse dependencies, use <code class="docutils literal notranslate"><span class="pre">python-r1</span></code>.</p></li>
<li><p>If the package (possibly conditionally) qualifies as using Python
at runtime, use <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>.</p></li>
<li><p>If the package uses Python at build time only, use <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code>.</p></li>
</ol>
</section>
<section id="python-utils-r1">
<h2>python-utils-r1<a class="headerlink" href="#python-utils-r1" title="Permalink to this headline">¶</a></h2>
<p>Besides the aforementioned eclasses, the suite includes a common utility
eclass <code class="docutils literal notranslate"><span class="pre">python-utils-r1</span></code>. This eclass is inherited by all other
eclasses, and it is considered to be a part of their API. Therefore,
it must not be inherited directly if any other of the eclasses
is inherited.</p>
<p>The only case for direct inherit of <code class="docutils literal notranslate"><span class="pre">python-utils-r1</span></code> is when you
are only using some of its utility functions without inheriting
any of the remaining eclasses. However, note that the majority of those
utility functions actually rely on mechanics provided by these eclasses
and are not suitable for being used otherwise.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1>
<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 current"><a class="current reference internal" href="#">Choosing between Python eclasses</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#build-time-vs-runtime-use">Build-time vs runtime use</a></li>
<li class="toctree-l2"><a class="reference internal" href="#single-impl-vs-multi-impl">Single-impl vs multi-impl</a></li>
<li class="toctree-l2"><a class="reference internal" href="#distutils-and-related-build-systems">Distutils and related build systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="#a-rule-of-thumb">A rule of thumb</a></li>
<li class="toctree-l2"><a class="reference internal" href="#python-utils-r1">python-utils-r1</a></li>
</ul>
</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="distutils-legacy.html">distutils-r1 legacy concepts</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="test.html">Resolving test suite problems</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"><a class="reference internal" href="migration.html">Migration guides</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="interpreter.html" title="previous chapter">Python interpreters</a></li>
<li>Next: <a href="basic.html" title="next chapter">Common basics</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<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"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2020, Michał Górny, license: CC BY 4.0.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 4.5.0</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="_sources/eclass.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|
GitWeb