# 3. Configurer Python

## 3.1. Options de configuration

Il est possible d'obtenir toutes les options de `./configure` avec :

    ./configure --help

Voir aussi le fichier `Misc/SpecialBuilds.txt` dans la distribution des sources Python.

### 3.1.1. Options générales

`--enable-loadable-sqlite-extensions```

  Active la prise en charge des extensions chargeables dans le module d'extension `_sqlite` (désactivé par défaut).

  Voir la méthode `sqlite3.Connection.enable_load_extension()` du module `sqlite3`.

  Nouveau dans la version 3.6.

`--disable-ipv6```

  Désactive la prise en charge d'IPv6 (activé par défaut si géré), voir le module `socket`.

`--enable-big-digits``=[15|30]`

  Définit la taille en bits des chiffres Python `int` : 15 ou 30 bits.

  By default, the number of bits is selected depending on `sizeof(void*)`: 30 bits if `void*` size is 64-bit or larger, 15 bits otherwise.

  Définit `PYLONG_BITS_IN_DIGIT` à `15` ou `30`.

  Voir `sys.int_info.bits_per_digit`.

`--with-cxx-main```

`--with-cxx-main``=COMPILER`

  Utilise le compilateur C++ (`$CXX`, ou COMPILER si spécifié) pour compiler la fonction Python `main()` et l'édition des liens de l'exécutable Python.

`--with-suffix``=SUFFIX`

  Définit à SUFFIX le suffixe de l'exécutable Python.

  The default suffix is `.exe` on Windows and macOS (`python.exe` executable), and an empty string on other platforms (`python` executable).

`--with-tzpath``=<list of absolute paths separated by pathsep>`

  Définit le chemin par défaut de recherche des fuseaux horaires pour `zoneinfo.TZPATH`. Voir la Configuration à la compilation du module `zoneinfo`.

  Par défaut : `/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo`.

  Voir le séparateur de chemins `os.pathsep`.

  Nouveau dans la version 3.9.

`--without-decimal-contextvar```

  Compile le module d'extension `_decimal` en utilisant un contexte local au fil d'exécution plutôt qu'un contexte local de coroutine (défaut). Voir le module `decimal`.

  Voir `decimal.HAVE_CONTEXTVAR` et le module `contextvars`.

  Nouveau dans la version 3.9.

`--with-dbmliborder``=db1:db2:...`

  Change l'ordre de détection des implémentations de base de données pour le module `dbm`.

  Une valeur valide est une chaîne de noms d'implémentations séparés par des deux-points (`:`).

  - `ndbm` ;

  - `gdbm` ;

  - `bdb`.

`--without-c-locale-coercion```

  Désactive le forçage des paramètres régionaux C pour un paramètre régional basé sur UTF-8 (activé par défaut).

  Ne pas définir la macro `PY_COERCE_C_LOCALE`.

  Voir `PYTHONCOERCECLOCALE` et la PEP 538.

`--with-platlibdir``=DIRNAME`

  Nom du dossier de bibliothèques Python (par défaut : `lib`).

  Fedora et SuSE utilisent `lib64` sur les systèmes 64-bit.

  Voir `sys.platlibdir`.

  Nouveau dans la version 3.9.

`--with-wheel-pkg-dir``=PATH`

  Dossier de paquets wheel utilisé par le module `ensurepip` (par défaut : aucun).

  La politique de paquets de certaines distributions Linux déconseille l'inclusion des dépendances. Par exemple, Fedora installe les paquets wheel dans le répertoire `/usr/share/python-wheels/` et n'installe pas le paquet `ensurepip._bundled`.

  Nouveau dans la version 3.10.

### 3.1.2. Options d'installation

`--prefix``=PREFIX`

  Install architecture-independent files in PREFIX. On Unix, it defaults to `/usr/local`.

  This value can be retrived at runtime using `sys.prefix`.

  As an example, one can use `--prefix="$HOME/.local/"` to install a Python in its home directory.

`--exec-prefix``=EPREFIX`

  Install architecture-dependent files in EPREFIX, defaults to `--prefix`.

  This value can be retrived at runtime using `sys.exec_prefix`.

`--disable-test-modules```

  Désactive la compilation et l'installation des modules de test, comme le paquet `test` et le module d'extension `_testcapi` (compilés et installés par défaut).

  Nouveau dans la version 3.10.

`--with-ensurepip``=[upgrade|install|no]`

  Sélectionne la commande `ensurepip` exécutée à l'installation de Python :

  - `upgrade` (défaut) : exécute la commande `python -m ensurepip --altinstall --upgrade` ;

  - `install` : exécute la commande `python -m ensurepip --altinstall` ;

  - `no` : n'exécute pas ensurepip.

  Nouveau dans la version 3.6.

### 3.1.3. Options de performance

Pour de meilleures performances, il est recommandé de configurer Python avec `--enable-optimizations --with-lto` (PGO + LTO).

`--enable-optimizations```

  Active l'optimisation guidée par profilage (Profile Guided Optimization, PGO) en utilisant `PROFILE_TASK` (désactivé par défaut).

  L'utilisation de PGO avec le compilateur C Clang nécessite `llvm-profdata`. Sur macOS, GCC est juste un alias vers Clang et partage donc cette contrainte.

  Désactive également l'interposition sémantique dans libpython si GCC est utilisé avec `--enable-shared` : ajoute l'option `-fno-semantic-interposition` à la compilation et à l'édition des liens.

  Nouveau dans la version 3.6.

  Modifié dans la version 3.10: Utilisation de `-fno-semantic-interposition` avec GCC.

`PROFILE_TASK`

  Variable d'environnement utilisée dans le `Makefile` : arguments Python utilisés pour la tâche de préparation de la PGO.

  Par défaut : `-m test --pgo --timeout=$(TESTTIMEOUT)`.

  Nouveau dans la version 3.8.

`--with-lto```

  Active l'optimisation à l'édition des liens (Link Time Optimization, LTO) à la compilation (désactivé par défaut).

  Le compilateur C Clang nécessite `llvm-ar` pour la LTO (`ar` sur macOS), ainsi qu'un éditeur de liens implémentant la LTO (`ld.gold` ou `lld`).

  Nouveau dans la version 3.6.

`--with-computed-gotos```

  Autorise les gotos calculés dans les boucles (activé par défaut pour les compilateurs qui le gèrent).

`--without-pymalloc```

  Désactive l'allocateur spécialisé de mémoire de Python pymalloc (activé par défaut).

  Voir aussi la variable d'environnement `PYTHONMALLOC`.

`--without-doc-strings```

  Désactive les chaînes de documentation statiques pour réduire l'empreinte mémoire (activé par défaut). Les chaînes définies dans Python ne sont pas affectées.

  Ne définit pas la macro `WITH_DOC_STRINGS`.

  Voir la macro `PyDoc_STRVAR()`.

`--enable-profiling```

  Active le profilage du code C avec `gprof` (désactivé par défaut).

### 3.1.4. Compilation de Python en mode débogage

Une compilation de Python en mode débogage se fait avec l'option de configuration `--with-pydebug`.

Effets du mode débogage :

- Affichage de tous les avertissements par défaut : le filtre par défaut des avertissements est vide dans le module `warnings`.

- Ajout de `d` à `sys.abiflags`.

- Ajout de la fonction `sys.gettotalrefcount()`.

- Ajout de l'option de ligne de commande `-X showrefcount`.

- Ajout de la variable d'environnement `PYTHONTHREADDEBUG`.

- Add support for the `__ltrace__` variable: enable low-level tracing in the bytecode evaluation loop if the variable is defined.

- Installation des debug hooks on memory allocators pour détecter les débordements de mémoire tampon et autres erreurs de mémoire.

- Définition des macros `Py_DEBUG` et `Py_REF_DEBUG`.

- Add runtime checks: code surroundeded by `#ifdef Py_DEBUG` and `#endif`. Enable `assert(...)` and `_PyObject_ASSERT(...)` assertions: don't set the `NDEBUG` macro (see also the `--with-assertions` configure option). Main runtime checks:

  - Ajout des contrôles d'intégrité sur les arguments de fonction.

  - Les objets `unicode` et `int` sont créés avec un motif particulier à l'initialisation de leur mémoire afin de détecter l'usage d'objets non initialisés.

  - S'assurer que les fonctions qui peuvent effacer ou remplacer l'exception courante ne sont pas appelées avec une exception levée.

  - Le ramasse-miettes (la fonction `gc.collect()`) effectue quelques tests basiques relatifs à la cohérence des objets.

  - La macro `Py_SAFE_DOWNCAST()` vérifie s'il y a des débordements d'entier lors du passage de types grands vers des types plus petits.

Voir aussi le mode de développement Python et l'option de configuration `--with-trace-refs`.

Modifié dans la version 3.8: Release builds and debug builds are now ABI compatible: defining the `Py_DEBUG` macro no longer implies the `Py_TRACE_REFS` macro (see the `--with-trace-refs` option), which introduces the only ABI incompatibility.

### 3.1.5. Debug options

`--with-pydebug```

  Build Python in debug mode: define the `Py_DEBUG` macro (disabled by default).

`--with-trace-refs```

  Enable tracing references for debugging purpose (disabled by default).

  Effects:

  - Define the `Py_TRACE_REFS` macro.

  - Add `sys.getobjects()` function.

  - Add `PYTHONDUMPREFS` environment variable.

  This build is not ABI compatible with release build (default build) or debug build (`Py_DEBUG` and `Py_REF_DEBUG` macros).

  Nouveau dans la version 3.8.

`--with-assertions```

  Build with C assertions enabled (default is no): `assert(...);` and `_PyObject_ASSERT(...);`.

  If set, the `NDEBUG` macro is not defined in the `OPT` compiler variable.

  See also the `--with-pydebug` option (debug build) which also enables assertions.

  Nouveau dans la version 3.6.

`--with-valgrind```

  Enable Valgrind support (default is no).

`--with-dtrace```

  Enable DTrace support (default is no).

  See Instrumenting CPython with DTrace and SystemTap.

  Nouveau dans la version 3.6.

`--with-address-sanitizer```

  Enable AddressSanitizer memory error detector, `asan` (default is no).

  Nouveau dans la version 3.6.

`--with-memory-sanitizer```

  Enable MemorySanitizer allocation error detector, `msan` (default is no).

  Nouveau dans la version 3.6.

`--with-undefined-behavior-sanitizer```

  Enable UndefinedBehaviorSanitizer undefined behaviour detector, `ubsan` (default is no).

  Nouveau dans la version 3.6.

### 3.1.6. Linker options

`--enable-shared```

  Enable building a shared Python library: `libpython` (default is no).

`--without-static-libpython```

  Do not build `libpythonMAJOR.MINOR.a` and do not install `python.o` (built and enabled by default).

  Nouveau dans la version 3.10.

### 3.1.7. Libraries options

`--with-libs``='lib1 ...'`

  Link against additional libraries (default is no).

`--with-system-expat```

  Build the `pyexpat` module using an installed `expat` library (default is no).

`--with-system-ffi```

  Build the `_ctypes` extension module using an installed `ffi` library, see the `ctypes` module (default is system-dependent).

`--with-system-libmpdec```

  Build the `_decimal` extension module using an installed `mpdec` library, see the `decimal` module (default is no).

  Nouveau dans la version 3.3.

`--with-readline``=editline`

  Use `editline` library for backend of the `readline` module.

  Define the `WITH_EDITLINE` macro.

  Nouveau dans la version 3.10.

`--without-readline```

  Don't build the `readline` module (built by default).

  Don't define the `HAVE_LIBREADLINE` macro.

  Nouveau dans la version 3.10.

`--with-tcltk-includes``='-I...'`

  Override search for Tcl and Tk include files.

`--with-tcltk-libs``='-L...'`

  Override search for Tcl and Tk libraries.

`--with-libm``=STRING`

  Override `libm` math library to STRING (default is system-dependent).

`--with-libc``=STRING`

  Override `libc` C library to STRING (default is system-dependent).

`--with-openssl``=DIR`

  Root of the OpenSSL directory.

  Nouveau dans la version 3.7.

`--with-openssl-rpath``=[no|auto|DIR]`

  Set runtime library directory (rpath) for OpenSSL libraries:

  - `no` (default): don't set rpath;

  - `auto`: auto-detect rpath from `--with-openssl` and `pkg-config`;

  - DIR: set an explicit rpath.

  Nouveau dans la version 3.10.

### 3.1.8. Security Options

`--with-hash-algorithm``=[fnv|siphash24]`

  Select hash algorithm for use in `Python/pyhash.c`:

  - `siphash24` (default).

  - `fnv`;

  Nouveau dans la version 3.4.

`--with-builtin-hashlib-hashes``=md5,sha1,sha256,sha512,sha3,blake2`

  Built-in hash modules:

  - `md5`;

  - `sha1`;

  - `sha256`;

  - `sha512`;

  - `sha3` (with shake);

  - `blake2`.

  Nouveau dans la version 3.9.

`--with-ssl-default-suites``=[python|openssl|STRING]`

  Override the OpenSSL default cipher suites string:

  - `python` (default): use Python's preferred selection;

  - `openssl`: leave OpenSSL's defaults untouched;

  - STRING: use a custom string

  See the `ssl` module.

  Nouveau dans la version 3.7.

  Modifié dans la version 3.10: The settings `python` and STRING also set TLS 1.2 as minimum protocol version.

### 3.1.9. macOS Options

See `Mac/README.rst`.

`--enable-universalsdk```

`--enable-universalsdk``=SDKDIR`

  Create a universal binary build. SDKDIR specifies which macOS SDK should be used to perform the build (default is no).

`--enable-framework```

`--enable-framework``=INSTALLDIR`

  Create a Python.framework rather than a traditional Unix install. Optional INSTALLDIR specifies the installation path (default is no).

`--with-universal-archs``=ARCH`

  Specify the kind of universal binary that should be created. This option is only valid when `--enable-universalsdk` is set.

  Options:

  - `universal2`;

  - `32-bit`;

  - `64-bit`;

  - `3-way`;

  - `intel`;

  - `intel-32`;

  - `intel-64`;

  - `all`.

`--with-framework-name``=FRAMEWORK`

  Specify the name for the python framework on macOS only valid when `--enable-framework` is set (default: `Python`).

## 3.2. Python Build System

### 3.2.1. Main files of the build system

- `configure.ac` => `configure`;

- `Makefile.pre.in` => `Makefile` (created by `configure`);

- `pyconfig.h` (created by `configure`);

- `Modules/Setup`: C extensions built by the Makefile using `Module/makesetup` shell script;

- `setup.py`: C extensions built using the `distutils` module.

### 3.2.2. Main build steps

- C files (`.c`) are built as object files (`.o`).

- A static `libpython` library (`.a`) is created from objects files.

- `python.o` and the static `libpython` library are linked into the final `python` program.

- C extensions are built by the Makefile (see `Modules/Setup`) and `python setup.py build`.

### 3.2.3. Main Makefile targets

- `make`: Build Python with the standard library.

- `make platform:`: build the `python` program, but don't build the standard library extension modules.

- `make profile-opt`: build Python using Profile Guided Optimization (PGO). You can use the configure `--enable-optimizations` option to make this the default target of the `make` command (`make all` or just `make`).

- `make buildbottest`: Build Python and run the Python test suite, the same way than buildbots test Python. Set `TESTTIMEOUT` variable (in seconds) to change the test timeout (1200 by default: 20 minutes).

- `make install`: Build and install Python.

- `make regen-all`: Regenerate (almost) all generated files; `make regen-stdlib-module-names` and `autoconf` must be run separately for the remaining generated files.

- `make clean`: Remove built files.

- `make distclean`: Same than `make clean`, but remove also files created by the configure script.

### 3.2.4. C extensions

Some C extensions are built as built-in modules, like the `sys` module. They are built with the `Py_BUILD_CORE_BUILTIN` macro defined. Built-in modules have no `__file__` attribute:

    >>> import sys
    >>> sys
    <module 'sys' (built-in)>
    >>> sys.__file__
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    AttributeError: module 'sys' has no attribute '__file__'

Other C extensins are built as dynamic libraries, like the `_asyncio` module. They are built with the `Py_BUILD_CORE_MODULE` macro defined. Example on Linux x86-64:

    >>> import _asyncio
    >>> _asyncio
    <module '_asyncio' from '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'>
    >>> _asyncio.__file__
    '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'

`Modules/Setup` is used to generate Makefile targets to build C extensions. At the beginning of the files, C extensions are built as built-in modules. Extensions defined after the `*shared*` marker are built as dynamic libraries.

The `setup.py` script only builds C extensions as shared libraries using the `distutils` module.

The `PyAPI_FUNC()`, `PyAPI_API()` and `PyMODINIT_FUNC()` macros of `Include/pyport.h` are defined differently depending if the `Py_BUILD_CORE_MODULE` macro is defined:

- Use `Py_EXPORTED_SYMBOL` if the `Py_BUILD_CORE_MODULE` is defined

- Use `Py_IMPORTED_SYMBOL` otherwise.

If the `Py_BUILD_CORE_BUILTIN` macro is used by mistake on a C extension built as a shared library, its `PyInit_xxx()` function is not exported, causing an `ImportError` on import.

## 3.3. Compiler and linker flags

Options set by the `./configure` script and environment variables and used by `Makefile`.

### 3.3.1. Preprocessor flags

`CONFIGURE_CPPFLAGS`

  Value of `CPPFLAGS` variable passed to the `./configure` script.

  Nouveau dans la version 3.6.

`CPPFLAGS`

  (Objective) C/C++ preprocessor flags, e.g. `-I<include dir>` if you have headers in a nonstandard directory `<include dir>`.

  Both `CPPFLAGS` and `LDFLAGS` need to contain the shell's value for setup.py to be able to build extension modules using the directories specified in the environment variables.

`BASECPPFLAGS`

  Nouveau dans la version 3.4.

`PY_CPPFLAGS`

  Extra preprocessor flags added for building the interpreter object files.

  Default: `$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)`.

  Nouveau dans la version 3.2.

### 3.3.2. Compiler flags

`CC`

  C compiler command.

  Example: `gcc -pthread`.

`MAINCC`

  C compiler command used to build the `main()` function of programs like `python`.

  Variable set by the `--with-cxx-main` option of the configure script.

  Default: `$(CC)`.

`CXX`

  C++ compiler command.

  Used if the `--with-cxx-main` option is used.

  Example: `g++ -pthread`.

`CFLAGS`

  C compiler flags.

`CFLAGS_NODIST`

  `CFLAGS_NODIST` is used for building the interpreter and stdlib C extensions. Use it when a compiler flag should not be part of the distutils `CFLAGS` once Python is installed (bpo-21121).

  In particular, `CFLAGS` should not contain:

  - the compiler flag `-I` (for setting the search path for include files). The `-I` flags are processed from left to right, and any flags in `CFLAGS` would take precedence over user- and package-supplied `-I` flags.

  - hardening flags such as `-Werror` because distributions cannot control whether packages installed by users conform to such heightened standards.

  Nouveau dans la version 3.5.

`EXTRA_CFLAGS`

  Extra C compiler flags.

`CONFIGURE_CFLAGS`

  Value of `CFLAGS` variable passed to the `./configure` script.

  Nouveau dans la version 3.2.

`CONFIGURE_CFLAGS_NODIST`

  Value of `CFLAGS_NODIST` variable passed to the `./configure` script.

  Nouveau dans la version 3.5.

`BASECFLAGS`

  Base compiler flags.

`OPT`

  Optimization flags.

`CFLAGS_ALIASING`

  Strict or non-strict aliasing flags used to compile `Python/dtoa.c`.

  Nouveau dans la version 3.7.

`CCSHARED`

  Compiler flags used to build a shared library.

  For example, `-fPIC` is used on Linux and on BSD.

`CFLAGSFORSHARED`

  Extra C flags added for building the interpreter object files.

  Default: `$(CCSHARED)` when `--enable-shared` is used, or an empty string otherwise.

`PY_CFLAGS`

  Default: `$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)`.

`PY_CFLAGS_NODIST`

  Default: `$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal`.

  Nouveau dans la version 3.5.

`PY_STDMODULE_CFLAGS`

  C flags used for building the interpreter object files.

  Default: `$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)`.

  Nouveau dans la version 3.7.

`PY_CORE_CFLAGS`

  Default: `$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE`.

  Nouveau dans la version 3.2.

`PY_BUILTIN_MODULE_CFLAGS`

  Compiler flags to build a standard library extension module as a built-in module, like the `posix` module.

  Default: `$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN`.

  Nouveau dans la version 3.8.

`PURIFY`

  Purify command. Purify is a memory debugger program.

  Default: empty string (not used).

### 3.3.3. Linker flags

`LINKCC`

  Linker command used to build programs like `python` and `_testembed`.

  Default: `$(PURIFY) $(MAINCC)`.

`CONFIGURE_LDFLAGS`

  Value of `LDFLAGS` variable passed to the `./configure` script.

  Avoid assigning `CFLAGS`, `LDFLAGS`, etc. so users can use them on the command line to append to these values without stomping the pre-set values.

  Nouveau dans la version 3.2.

`LDFLAGS_NODIST`

  `LDFLAGS_NODIST` is used in the same manner as `CFLAGS_NODIST`. Use it when a linker flag should not be part of the distutils `LDFLAGS` once Python is installed (bpo-35257).

  In particular, `LDFLAGS` should not contain:

  - the compiler flag `-L` (for setting the search path for libraries). The `-L` flags are processed from left to right, and any flags in `LDFLAGS` would take precedence over user- and package-supplied `-L` flags.

`CONFIGURE_LDFLAGS_NODIST`

  Value of `LDFLAGS_NODIST` variable passed to the `./configure` script.

  Nouveau dans la version 3.8.

`LDFLAGS`

  Linker flags, e.g. `-L<lib dir>` if you have libraries in a nonstandard directory `<lib dir>`.

  Both `CPPFLAGS` and `LDFLAGS` need to contain the shell's value for setup.py to be able to build extension modules using the directories specified in the environment variables.

`LIBS`

  Linker flags to pass libraries to the linker when linking the Python executable.

  Example: `-lrt`.

`LDSHARED`

  Command to build a shared library.

  Default: `@LDSHARED@ $(PY_LDFLAGS)`.

`BLDSHARED`

  Command to build `libpython` shared library.

  Default: `@BLDSHARED@ $(PY_CORE_LDFLAGS)`.

`PY_LDFLAGS`

  Default: `$(CONFIGURE_LDFLAGS) $(LDFLAGS)`.

`PY_LDFLAGS_NODIST`

  Default: `$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)`.

  Nouveau dans la version 3.8.

`PY_CORE_LDFLAGS`

  Linker flags used for building the interpreter object files.

  Nouveau dans la version 3.8.