path: root/chapter08/python.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>

<sect1 id="ch-system-Python" role="wrap">
  <?dbhtml filename="Python.html"?>

  <sect1info condition="script">
    <productname>Python</productname>
    <productnumber>&python-version;</productnumber>
    <address>&python-url;</address>
  </sect1info>

  <title>Python-&python-version;</title>

  <indexterm zone="ch-system-Python">
    <primary sortas="a-Python">Python</primary>
  </indexterm>

  <sect2 role="package">
    <title/>

    <para>The Python 3 package contains the Python development environment. It
    is useful for object-oriented programming, writing scripts, prototyping
    large programs, or developing entire applications.</para>

    <segmentedlist>
      <segtitle>&buildtime;</segtitle>
      <segtitle>&diskspace;</segtitle>

      <seglistitem>
        <seg>&python-fin-sbu;</seg>
        <seg>&python-fin-du;</seg>
      </seglistitem>
    </segmentedlist>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Python 3</title>

    <para>Prepare Python for compilation:</para>

<screen><userinput remap="configure">./configure --prefix=/usr        \
            --enable-shared      \
            --with-system-expat  \
            --with-system-ffi    \
            --enable-optimizations</userinput></screen>

    <variablelist>
      <title>The meaning of the configure options:</title>

    <varlistentry>
      <term><parameter>--with-system-expat</parameter></term>
      <listitem>
        <para>This switch enables linking against system version of
        <application>Expat</application>.</para>
       </listitem>
     </varlistentry>

    <varlistentry>
      <term><parameter>--with-system-ffi</parameter></term>
      <listitem>
        <para>This switch enables linking against system version of
        <application>libffi</application>.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><parameter>--enable-optimizations</parameter></term>
      <listitem>
        <para>This switch enables stable, but expensive, optimizations.</para>
      </listitem>
    </varlistentry>

    </variablelist>

    <para>Compile the package:</para>

<screen><userinput remap="make">make</userinput></screen>

    <para>Running the tests at this point is not recommended.  The
    tests are known to hang indefinitely in the partial LFS environment.
    If desired, the tests can be rerun at the end of this chapter or
    when Python 3 is reinstalled in BLFS.  To run the tests anyway,
    issue <command>make test</command>.</para>

    <para>Install the package:</para>

<screen><userinput remap="install">make install</userinput></screen>

    <para>In several places we use the <command>pip3</command> command to
    install Python 3 programs and modules for all users as
    <systemitem class='username'>root</systemitem>. This conflicts
    with the Python developers recommendation to install packages into a
    virtual environment or the home directory of a regular user (by running
    <command>pip3</command> as this user). To this end, a multi-line warning
    is written when using <command>pip3</command> as the
    <systemitem class='username'>root</systemitem> user.  The main reason
    of this recommendation is for avoiding a conflict with the system
    package manager (<command>dpkg</command> for example), but LFS does not
    have a system-wide package manager so this is not a problem.  And,
    <command>pip3</command> will attempt to check for a new version of
    itself whenever it's run.  As domain name resolving is not configured
    yet in LFS chroot environment, it will fail to check for a new version
    and produce a warning.  Once we boot the LFS system and set up network
    connection, it will then produce a warning telling the user to update it
    from a pre-built wheel on PyPI if any new version is available.  But LFS
    consider <command>pip3</command> a part of Python 3 so it should not be
    updated separately, and an update from a pre-built wheel will deviate
    from our purpose to build a Linux system from source code.  So the
    warning for a new <command>pip3</command> version should be ignored as
    well. If desired, suppress these warnings by running the following
    commands:</para>

<screen><userinput remap="install">cat &gt; /etc/pip.conf &lt;&lt; EOF
<literal>[global]
root-user-action = ignore
disable-pip-version-check = true</literal>
EOF
</userinput></screen>
<!--
<screen><userinput remap="install">sed -e '/def warn_if_run_as_root/a\    return' \
    -i /usr/lib/python3.10/site-packages/pip/_internal/cli/req_command.py
</userinput></screen>
-->
    <important>
      <para>
        In LFS and BLFS we normally build and install Python modules with the
        <command>pip3</command> command.  Please take care that the
        <command>pip3 install</command> commands in both the books should be
        run as the &root; user unless it's for a Python virtual environment.
        Running a <command>pip3 install</command> as a non-&root; user may seem
        to work fine, but it will cause the installed module to be inaccessible
        by other users.
      </para>

      <para>
        <command>pip3 install</command> will not reinstall an already installed
        module by default.  For using the <command>pip3 install</command>
        command to upgrade a module (for example, from meson-0.61.3 to
        meson-0.62.0), insert the option <parameter>--upgrade</parameter> into
        the command line.  If it's really necessary to downgrade a module or
        reinstall the same version for some reason, insert
        <parameter>--force-reinstall --no-deps</parameter> into the command
        line.
      </para>
    </important>

    <para>If desired, install the preformatted documentation:</para>

<screen><userinput remap="install">install -v -dm755 /usr/share/doc/python-&python-version;/html

tar --strip-components=1  \
    --no-same-owner       \
    --no-same-permissions \
    -C /usr/share/doc/python-&python-version;/html \
    -xvf ../python-&python-version;-docs-html.tar.bz2</userinput></screen>

    <variablelist>
      <title>The meaning of the documentation install commands:</title>

    <varlistentry>
      <term><option>--no-same-owner</option> and <option>--no-same-permissions</option></term>
      <listitem>
        <para>Ensure the installed files have the correct ownership and
        permissions.  Without these options, using <application>tar</application>
        will install the package files with the upstream creator's values.
        </para>
      </listitem>
    </varlistentry>

    </variablelist>

  </sect2>

  <sect2 id="contents-python" role="content">
    <title>Contents of Python 3</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          2to3, idle3, pip3, pydoc3, python3, and python3-config
        </seg>
        <seg>
          libpython&python-minor;.so and libpython3.so
        </seg>
        <seg>
          /usr/include/python&python-minor;,
          /usr/lib/python3, and
          /usr/share/doc/python-&python-version;
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="python-2to3">
        <term><command>2to3</command></term>
        <listitem>
          <para>
            is a <application>Python</application> program that reads
            <application>Python 2.x</application> source code and applies a
            series of fixes to transform it into
            valid <application>Python 3.x</application> code
          </para>
          <indexterm zone="ch-system-Python">
            <primary sortas="b-2to3">2to3</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="idle3">
        <term><command>idle3</command></term>
        <listitem>
          <para>
            is a wrapper script that opens a <application>Python</application>
            aware GUI editor. For this script to run, you must have installed
            <application>Tk</application> before Python so that the Tkinter
            Python module is built
          </para>
          <indexterm zone="ch-system-Python">
            <primary sortas="b-idle3">idle3</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pip3">
        <term><command>pip3</command></term>
        <listitem>
          <para>
            The package installer for Python. You can use pip to install
            packages from Python Package Index and other indexes
          </para>
          <indexterm zone="ch-system-Python">
            <primary sortas="b-pip3">pip3</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pydoc3">
        <term><command>pydoc3</command></term>
        <listitem>
          <para>
            is the <application>Python</application> documentation tool
          </para>
          <indexterm zone="ch-system-Python">
            <primary sortas="b-pydoc3">pydoc3</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="python3">
        <term><command>python3</command></term>
        <listitem>
          <para>
            is an interpreted, interactive, object-oriented programming
            language
          </para>
          <indexterm zone="ch-system-Python">
            <primary sortas="b-python3">python3</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>