bpo-36797: Prune more legacy distutils documentation (GH-13092) · python/cpython@dae1229 (original) (raw)

`@@ -13,23 +13,10 @@

13

`.. seealso::

14

15

`` :ref:installing-index

16

The up to date module installation documentations

17

-

18

.. The audience for this document includes people who don't know anything

19

about Python and aren't about to learn the language just in order to

20

install and maintain it for their users, i.e. system administrators.

21

Thus, I have to be sure to explain the basics at some point:

22

sys.path and PYTHONPATH at least. Should probably give pointers to

23

other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.

24

-

25

Finally, it might be useful to include all the material from my "Care

26

and Feeding of a Python Installation" talk in here somewhere. Yow!

27

-

28

This document describes the Python Distribution Utilities ("Distutils") from the

29

end-user's point-of-view, describing how to extend the capabilities of a

30

standard Python installation by building and installing third-party Python

31

modules and extensions.

16

The up to date module installation documentation. For regular Python

17

usage, you almost certainly want that document rather than this one.

32

18

19

.. include:: ../distutils/_setuptools_disclaimer.rst

33

20

34

21

`.. note::

35

22

`@@ -46,59 +33,26 @@ modules and extensions.

46

33

`Introduction

47

34

`============

48

35

49

Although Python's extensive standard library covers many programming needs,

50

there often comes a time when you need to add some new functionality to your

51

Python installation in the form of third-party modules. This might be necessary

52

to support your own programming, or to support an application that you want to

53

use and that happens to be written in Python.

54

-

55

In the past, there has been little support for adding third-party modules to an

56

existing Python installation. With the introduction of the Python Distribution

57

Utilities (Distutils for short) in Python 2.0, this changed.

58

-

59

This document is aimed primarily at the people who need to install third-party

60

Python modules: end-users and system administrators who just need to get some

61

Python application running, and existing Python programmers who want to add some

62

new goodies to their toolbox. You don't need to know Python to read this

63

document; there will be some brief forays into using Python's interactive mode

64

to explore your installation, but that's it. If you're looking for information

65

on how to distribute your own Python modules so that others may use them, see

66

`` -

the :ref:distutils-index manual. :ref:debug-setup-script may also be of

67

interest.

68

-

69

-

70

.. _inst-trivial-install:

71

-

72

Best case: trivial installation

73

74

-

75

In the best case, someone will have prepared a special version of the module

76

distribution you want to install that is targeted specifically at your platform

77

and is installed just like any other software on your platform. For example,

78

the module developer might make an executable installer available for Windows

79

users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE,

80

Mandrake, and many others), a Debian package for users of Debian-based Linux

81

systems, and so forth.

82

-

83

In that case, you would download the installer appropriate to your platform and

84


do the obvious thing with it: run it if it's an executable installer, ``rpm

85


--install`` it if it's an RPM, etc. You don't need to run Python or a setup

86

script, you don't need to compile anything---you might not even need to read any

87

instructions (although it's always a good idea to do so anyway).

88

-

89

Of course, things will not always be that easy. You might be interested in a

90

module distribution that doesn't have an easy-to-use installer for your

91

platform. In that case, you'll have to start with the source distribution

92

released by the module's author/maintainer. Installing from a source

93

distribution is not too hard, as long as the modules are packaged in the

94

standard way. The bulk of this document is about building and installing

95

modules from standard source distributions.

36


In Python 2.0, the ``distutils`` API was first added to the standard library.

37

This provided Linux distro maintainers with a standard way of converting

38

Python projects into Linux distro packages, and system administrators with a

39

standard way of installing them directly onto target systems.

40

+

41

In the many years since Python 2.0 was released, tightly coupling the build

42

system and package installer to the language runtime release cycle has turned

43

out to be problematic, and it is now recommended that projects use the

44


``pip`` package installer and the ``setuptools`` build system, rather than

45


using ``distutils`` directly.

46

+

47

`` +

See :ref:installing-index and :ref:distributing-index for more details.

96

48

49

This legacy documentation is being retained only until we're confident that the

50


``setuptools`` documentation covers everything needed.

97

51

98

52

`.. _inst-new-standard:

99

53

100

The new standard: Distutils

101

54

Distutils based source distributions

55

102

56

103

57

`If you download a module source distribution, you can tell pretty quickly if it

104

58

`was packaged and distributed in the standard way, i.e. using the Distutils.