Instalando módulos Python (versão legada)
*****************************************

Autor:
   Greg Ward

Nota:

  Todo o pacote "distutils" foi descontinuado e será removido no
  Python 3.12. Esta documentação é mantida apenas como referência e
  será removida com o pacote. Veja a entrada no O que há de novo para
  mais informações.

Ver também:

  Instalando módulos Python
     A documentação de instalação do módulo atualizada. Para o uso
     regular do Python, você provavelmente deseja aquela documentação
     em vez desta.

Nota:

  Este documento está sendo mantido apenas até que a documentação do
  "setuptools" em
  https://setuptools.readthedocs.io/en/latest/setuptools.html cubra
  independentemente todas as informações relevantes atualmente
  incluídas aqui.

Nota:

  Este guia cobre apenas as ferramentas básicas para construir e
  distribuir extensões que são fornecidas como parte desta versão do
  Python. Ferramentas de terceiros oferecem alternativas mais fáceis
  de usar e mais seguras. Consulte a quick recommendations section no
  Guia do Usuário de Pacotes Python para maiores informações


Introdução
==========

No Python 2.0, a API "distutils" foi adicionada pela primeira vez à
biblioteca padrão. Isso forneceu aos mantenedores das distros Linux
uma maneira padrão de converter projetos Python em pacotes de distro
Linux, e aos administradores de sistema uma maneira padrão de
instalá-los diretamente nos sistemas de destino.

Nos muitos anos desde que o Python 2.0 foi lançado, acoplar fortemente
o sistema de compilação e o instalador do pacote ao ciclo de
lançamento do tempo de execução da linguagem tornou-se problemático e
agora é recomendado que os projetos usem o instalador de pacotes "pip"
e o sistema de compilação "setuptools", ao invés de usar "distutils"
diretamente.

Veja Instalando módulos Python e Distribuindo módulos Python para mais
detalhes.

Esta documentação legada está sendo mantida apenas até que tenhamos
certeza de que a documentação do "setuptools" cobre tudo o que é
necessário.


Distribuições de fonte baseadas em Distutils
--------------------------------------------

Se você fizer o download de uma distribuição fonte do módulo, poderá
saber rapidamente se ele foi empacotado e distribuído da maneira
padrão, ou seja, usando o Distutils. Primeiro, o nome da distribuição
e o número da versão aparecerão de forma proeminente no nome do
arquivo baixado, por exemplo, "foo-1.0.tar.gz" ou "widget-0.9.7.zip".
Em seguida, o arquivo será descompactado em um diretório com nome
semelhante: "foo-1.0" ou "widget-0.9.7". Além disso, a distribuição
conterá um script de configuração "setup.py", e um arquivo chamado
"README.txt" ou possivelmente apenas "README", que deve explicar a
construção e instalação da distribuição de módulo é uma simples
questão de executar um comando de um terminal:

   python setup.py install

Para Windows, este comando deve ser executado de uma janela de prompt
de comando (Iniciar ‣ Acessórios):

   setup.py install

Se tudo isso for verdade, então você já sabe como construir e instalar
os módulos que acabou de baixar: execute o comando acima. A menos que
você precise instalar coisas de uma maneira não padronizada ou
personalizar o processo de construção, você realmente não precisa
deste manual. Ou melhor, o comando acima é tudo que você precisa para
extrair deste manual.


Construção e instalação padrão
==============================

Conforme descrito na seção Distribuições de fonte baseadas em
Distutils, construir e instalar uma distribuição de módulo usando o
Distutils é geralmente um comando simples para executar a partir de um
terminal:

   python setup.py install


Variações de plataforma
-----------------------

Você deve sempre executar o comando de configuração a partir do
diretório raiz da distribuição, ou seja, o subdiretório de nível
superior no qual a distribuição fonte do módulo descompacta. Por
exemplo, se você acabou de baixar uma distribuição fonte do módulo
"foo-1.0.tar.gz" em um sistema Unix, a coisa normal a fazer é:

   gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
   cd foo-1.0
   python setup.py install

No Windows, você provavelmente baixaria "foo-1.0.zip". Se você baixou
o arquivo para "C:\Temp", então ele seria descompactado em
"C:\Temp\foo-1.0"; você pode usar um manipulador de arquivo com uma
interface gráfica de usuário (como WinZip) ou uma ferramenta de linha
de comando (como **unzip** ou **pkunzip**) para descompactar o
arquivo. Em seguida, abra uma janela de prompt de comando e execute:

   cd c:\Temp\foo-1.0
   python setup.py install


Dividindo o trabalho
--------------------

A execução de "setup.py install" constrói e instala todos os módulos
de uma vez. Se você preferir trabalhar de forma incremental --
especialmente útil se quiser personalizar o processo de construção ou
se as coisas estiverem dando errado -- você pode usar o script de
configuração para fazer uma coisa por vez. Isto é particularmente útil
quando a construção e instalação serão feitas por usuários diferentes
-- por exemplo, você pode querer construir uma distribuição de módulo
e entregá-la a um administrador de sistema para instalação (ou faça
você mesmo, com privilégios de superusuário).

Por exemplo, você pode construir tudo em uma etapa e, em seguida,
instalar tudo em uma segunda etapa, invocando o script de configuração
duas vezes:

   python setup.py build
   python setup.py install

Se você fizer isso, você notará que executar o comando **install**
primeiro executa o comando **build**, que -- neste caso -- rapidamente
nota que não tem nada a fazer, já que tudo no diretório "build" está
atualizado.

Você pode não precisar dessa habilidade para quebrar as coisas com
frequência se tudo o que fizer for instalar módulos baixados da rede,
mas é muito útil para tarefas mais avançadas. Se você começar a
distribuir seus próprios módulos e extensões Python, executará muitos
comandos distutils individuais por conta própria.


Como a construção funciona
--------------------------

Como implícito acima, o comando **build** é responsável por colocar os
arquivos a serem instalados em um *diretório de construção*. Por
padrão, é "build" na raiz da distribuição; se você está excessivamente
preocupado com a velocidade, ou deseja manter a árvore de fontes
intocada, você pode alterar o diretório de construção com a opção "--
build-base". Por exemplo:

   python setup.py build --build-base=/path/to/pybuild/foo-1.0

(Ou você poderia fazer isso permanentemente com uma diretiva em seu
sistema ou arquivo de configuração pessoal do Distutils; consulte a
seção Arquivos de configuração do Distutils.) Normalmente, isso não é
necessário.

O layout padrão para a árvore de construção é o seguinte:

   --- build/ --- lib/
   or
   --- build/ --- lib.<plat>/
                  temp.<plat>/

onde "<plat>" expande-se para uma breve descrição do sistema
operacional/plataforma de hardware atual e versão Python. A primeira
forma, com apenas um diretório "lib", é usada para "distribuições de
módulos puros" -- isto é, distribuições de módulos que incluem apenas
módulos Python puros. Se uma distribuição de módulo contém quaisquer
extensões (módulos escritos em C/C++), então a segunda forma, com dois
diretórios "<plat>", é usada. Nesse caso, o diretório "temp.*plat*"
contém arquivos temporários gerados pelo processo de
compilação/vinculação que não são realmente instalados. Em ambos os
casos, o diretório "lib" (ou "lib.*plat*") contém todos os módulos
Python (Python puro e extensões) que serão instalados.

No futuro, mais diretórios serão adicionados para lidar com scripts
Python, documentação, executáveis binários e tudo o mais que for
necessário para lidar com o trabalho de instalação de módulos e
aplicações Python.


Como a instalação funciona
--------------------------

Depois que o comando **build** é executado (se você o executa
explicitamente ou o comando **install** faz isso por você), o trabalho
do comando **install** é relativamente simples: tudo o que ele tem a
fazer é copiar tudo em "build/lib" (ou "build/lib.*plat*") para o
diretório de instalação escolhido.

Se você não escolher um diretório de instalação -- ou seja, se você
apenas executar "setup.py install"-- então o comando **install**
instala no local padrão para módulos Python de terceiros . Esse local
varia de acordo com a plataforma e como você construiu/instalou o
próprio Python. No Unix (e no macOS, que também é baseado no Unix),
também depende se a distribuição de módulo que está sendo instalada é
Python puro ou contém extensões ("não puras"):

+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| Plataforma        | Local de instalação padrão                            | Valor padrão                                       | Notas   |
|===================|=======================================================|====================================================|=========|
| Unix (puro)       | "*prefix*/lib/python*X.Y*/site-packages"              | "/usr/local/lib/python*X.Y*/site-packages"         | (1)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| Unix (não puro)   | "*exec-prefix*/lib/python*X.Y*/site-packages"         | "/usr/local/lib/python*X.Y*/site-packages"         | (1)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| Windows           | "*prefix*\Lib\site-packages"                          | "C:\Python*XY*\Lib\site-packages"                  | (2)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+

Notas:

1. A maioria das distribuições Linux inclui Python como uma parte
   padrão do sistema, então "*prefix*" e "*exec-prefix*" são
   geralmente "/usr" no Linux. Se você construir Python no Linux (ou
   qualquer sistema semelhante ao Unix), o padrão de "*prefix*" e
   "*exec-prefix*" é "/usr/local".

2. O diretório de instalação padrão no Windows era "C:\Program
   Files\Python" no Python 1.6a1, 1.5.2 e anterior.

"*prefix*" e "*exec-prefix*" representam os diretórios nos quais o
Python é instalado e onde ele encontra suas bibliotecas em tempo de
execução. Eles são sempre os mesmos no Windows, e muitas vezes os
mesmos no Unix e macOS. Você pode descobrir o que sua instalação
Python usa para "*prefix*" e "*exec-prefix*" executando Python no modo
interativo e digitando alguns comandos simples. No Unix, apenas digite
"python" no prompt do shell. No Windows, escolha Iniciar ‣ Programas ‣
Python X.Y ‣ Python (command line). Depois que o interpretador é
iniciado, você digita o código Python no prompt. Por exemplo, em meu
sistema Linux, eu digito as três instruções Python mostradas abaixo e
obtenho a saída conforme mostrado, para descobrir meu "*prefix*" e
"*exec-prefix*":

   Python 2.4 (#26, Aug  7 2004, 17:19:02)
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import sys
   >>> sys.prefix
   '/usr'
   >>> sys.exec_prefix
   '/usr'

Alguns outros espaços reservados são usados neste documento: "*X.Y*"
representa a versão do Python, por exemplo "3.2"; "*abiflags*" será
substituído pelo valor de "sys.abiflags" ou pela string vazia para
plataformas que não definem sinalizadores ABI; "*distname*" será
substituído pelo nome da distribuição de módulo sendo instalado.
Pontos e letras maiúsculas são importantes nos caminhos; por exemplo,
um valor que usa "python3.2" no UNIX normalmente usará "Python32" no
Windows.

Se você não deseja instalar módulos no local padrão, ou se não tem
permissão para escrever lá, então você precisa ler sobre instalações
alternativas na seção Instalação alternativa. Se você deseja
personalizar seus diretórios de instalação mais intensamente, consulte
a seção Instalação personalizada sobre instalações personalizadas.


Instalação alternativa
======================

Frequentemente, é necessário ou desejável instalar módulos em um local
diferente do local padrão para módulos Python de terceiros. Por
exemplo, em um sistema Unix, você pode não ter permissão para escrever
no diretório de módulo de terceiros padrão. Ou você pode querer
experimentar um módulo antes de torná-lo uma parte padrão da
instalação local do Python. Isso é especialmente verdadeiro ao
atualizar uma distribuição já presente: você deseja ter certeza de que
sua base de scripts existente ainda funciona com a nova versão antes
de realmente atualizar.

O comando **install** do Distutils é projetado para tornar a
instalação de distribuições de módulos em um local alternativo simples
e indolor. A ideia básica é que você forneça um diretório base para a
instalação, e o comando **install** escolhe um conjunto de diretórios
(chamado de *esquema de instalação*) neste diretório base no qual
deseja instalar os arquivos. Os detalhes variam entre as plataformas,
portanto, leia qualquer uma das seções a seguir que se aplique a você.

Observe que os vários esquemas de instalação alternativos são
mutuamente exclusivos: você pode passar "--user", ou "--home", ou "--
prefix" e "--exec-prefix", ou "--install-base" e "--install-platbase",
mas você não pode misturar a partir destes grupos.


Instalação alternativa: o esquema usuário
-----------------------------------------

Este esquema foi projetado para ser a solução mais conveniente para
usuários que não têm permissão de escrita no diretório global de
pacotes de sites ou não desejam instalar nele. É habilitado com uma
opção simples:

   python setup.py install --user

Os arquivos serão instalados em subdiretórios de "site.USER_BASE"
(escrito como "*userbase*" daqui em diante). Este esquema instala
módulos Python puros e módulos de extensão no mesmo local (também
conhecido como "site.USER_SITE"). Aqui estão os valores para UNIX,
incluindo macOS:

+-----------------+-------------------------------------------------------------+
| Tipo de arquivo | Diretório de instalação                                     |
|=================|=============================================================|
| módulos         | "*userbase*/lib/python*X.Y*/site-packages"                  |
+-----------------+-------------------------------------------------------------+
| scripts         | "*userbase*/bin"                                            |
+-----------------+-------------------------------------------------------------+
| dados           | "*userbase*"                                                |
+-----------------+-------------------------------------------------------------+
| cabeçalhos do C | "*userbase*/include/python*X.Y**abiflags*/*distname*"       |
+-----------------+-------------------------------------------------------------+

E aqui estão os valores usados no Windows:

+-----------------+-------------------------------------------------------------+
| Tipo de arquivo | Diretório de instalação                                     |
|=================|=============================================================|
| módulos         | "*userbase*\Python*XY*\site-packages"                       |
+-----------------+-------------------------------------------------------------+
| scripts         | "*userbase*\Python*XY*\Scripts"                             |
+-----------------+-------------------------------------------------------------+
| dados           | "*userbase*"                                                |
+-----------------+-------------------------------------------------------------+
| cabeçalhos do C | "*userbase*\Python*XY*\Include{distname}"                   |
+-----------------+-------------------------------------------------------------+

A vantagem de usar este esquema em comparação com os outros descritos
abaixo é que o diretório de pacotes do site do usuário está, em
condições normais, sempre incluído em "sys.path" (veja "site" para
mais informações), o que significa que não há etapa adicional a ser
executada após a execução do script "setup.py" para finalizar a
instalação.

O comando **build_ext** também tem uma opção "--user" para adicionar
"*userbase*/include" ao caminho de pesquisa do compilador para
arquivos de cabeçalho e "*userbase*/lib" para o caminho de pesquisa do
compilador para bibliotecas, bem como para o caminho de pesquisa em
tempo de execução para bibliotecas C compartilhadas (rpath).


Instalação alternativa: o esquema home
--------------------------------------

A ideia por trás do "esquema home" é que você construa e mantenha um
estoque pessoal de módulos Python. O nome deste esquema é derivado da
ideia de um diretório "home" no Unix, uma vez que não é incomum para
um usuário Unix fazer seu diretório home ter um layout semelhante a
"/usr/" ou "/usr/local/". Este esquema pode ser usado por qualquer
pessoa, independentemente do sistema operacional para o qual está
instalando.

Instalando uma nova distribuição de módulo é tão simples quanto

   python setup.py install --home=<dir>

onde você pode fornecer qualquer diretório que desejar para a opção "
--home". No Unix, digitadores preguiçosos podem simplesmente digitar
um til ("~"); o comando **install** vai expandir isso para o seu
diretório home:

   python setup.py install --home=~

To make Python find the distributions installed with this scheme, you
may have to modify Python's search path or edit "sitecustomize" (see
"site") to call "site.addsitedir()" or edit "sys.path".

A opção "--home" define o diretório base de instalação. Os arquivos
são instalados nos seguintes diretórios na base de instalação da
seguinte maneira:

+-----------------+-------------------------------------------------------------+
| Tipo de arquivo | Diretório de instalação                                     |
|=================|=============================================================|
| módulos         | "*home*/lib/python"                                         |
+-----------------+-------------------------------------------------------------+
| scripts         | "*home*/bin"                                                |
+-----------------+-------------------------------------------------------------+
| dados           | "*home*"                                                    |
+-----------------+-------------------------------------------------------------+
| cabeçalhos do C | "*home*/include/python/*distname*"                          |
+-----------------+-------------------------------------------------------------+

(Substitua mentalmente as barras por contrabarras se estiver no
Windows.)


Instalação alternativa: Unix (o esquema prefixo)
------------------------------------------------

O "esquema prefixo" é útil quando você deseja usar uma instalação
Python para realizar a compilação/instalação (ou seja, para executar o
script de configuração), mas instalar módulos no diretório de módulo
de terceiros de uma instalação Python diferente (ou algo que parece
uma instalação diferente do Python). Se isso parece um pouco incomum,
então é -- é por isso que os esquemas usuário e home vêm antes. No
entanto, existem pelo menos dois casos conhecidos em que o esquema
prefixo será útil.

Primeiro, considere que muitas distribuições Linux colocam Python em
"/usr", ao invés do mais tradicional "/usr/local". Isso é totalmente
apropriado, já que, nesses casos, o Python é parte do "sistema" em vez
de um complemento local. No entanto, se você estiver instalando
módulos Python a partir do código-fonte, provavelmente deseja que eles
entrem em "/usr/local/lib/python2.*X*" em vez de
"/usr/lib/python2.*X*". Isso pode ser feito com

   /usr/bin/python setup.py install --prefix=/usr/local

Outra possibilidade é um sistema de arquivos de rede onde o nome usado
para escrever em um diretório remoto é diferente do nome usado para
lê-lo: por exemplo, o interpretador Python acessado como
"/usr/local/bin/python" pode pesquisar por módulos em
"/usr/local/lib/python2.*X*", mas esses módulos teriam que ser
instalados em, digamos, "/mnt/*@server*/export/lib/python2.*X*". Isso
pode ser feito com

   /usr/local/bin/python setup.py install --prefix=/mnt/@server/export

Em ambos os casos, a opção "--prefix" define a base de instalação, e a
opção "--exec-prefix" define a base de instalação específica da
plataforma, que é usada para arquivos específicos da plataforma.
(Atualmente, isso significa apenas distribuições de módulos não puros,
mas pode ser expandido para bibliotecas C, executáveis binários, etc.)
Se "--exec-prefix" não for fornecido, o padrão é "--prefix". Os
arquivos são instalados da seguinte forma:

+-------------------+------------------------------------------------------------+
| Tipo de arquivo   | Diretório de instalação                                    |
|===================|============================================================|
| módulos Python    | "*prefix*/lib/python*X.Y*/site-packages"                   |
+-------------------+------------------------------------------------------------+
| módulos de        | "*exec-prefix*/lib/python*X.Y*/site-packages"              |
| extensão          |                                                            |
+-------------------+------------------------------------------------------------+
| scripts           | "*prefix*/bin"                                             |
+-------------------+------------------------------------------------------------+
| dados             | "*prefix*"                                                 |
+-------------------+------------------------------------------------------------+
| cabeçalhos do C   | "*prefix*/include/python*X.Y**abiflags*/*distname*"        |
+-------------------+------------------------------------------------------------+

Não há nenhum requisito de que "--prefix" ou "--exec-prefix" realmente
apontem para uma instalação alternativa do Python; se os diretórios
listados acima ainda não existirem, eles serão criados no momento da
instalação.

A propósito, a verdadeira razão pela qual o esquema prefixo é
importante é simplesmente que uma instalação Unix padrão usa o esquema
prefixo, mas com "--prefix" e "--exec-prefix" fornecidos pelo próprio
Python como "sys.prefix" e "sys.exec_prefix". Portanto, você pode
pensar que nunca usará o esquema prefixo, mas toda vez que executa
"python setup.py install" sem qualquer outra opção, você o está
usando.

Observe que instalar extensões para uma instalação alternativa do
Python não tem efeito sobre como essas extensões são construídas: em
particular, os arquivos de cabeçalho Python ("Python.h" e amigos)
instalados com o interpretador Python usado para executar o script de
configuração vão ser usador na compilação de extensões. É sua
responsabilidade garantir que o interpretador usado para executar as
extensões instaladas dessa maneira seja compatível com o interpretador
usado para criá-las. A melhor maneira de fazer isso é garantir que os
dois interpretadores sejam da mesma versão do Python (possivelmente
compilações diferentes ou possivelmente cópias da mesma compilação).
(Claro, se seu "--prefix" e seu "--exec-prefix" nem mesmo apontam para
uma instalação alternativa do Python, isso é imaterial.)


Instalação alternativa: Windows (o esquema prefixo)
---------------------------------------------------

O Windows não tem o conceito de diretório pessoal do usuário e, como a
instalação padrão do Python no Windows é mais simples do que no Unix,
a opção "--prefix" tem sido tradicionalmente usada para instalar
pacotes adicionais em locais separados no Windows.

   python setup.py install --prefix="\Temp\Python"

para instalar módulos para o diretório "\Temp\Python" na unidade
atual.

A base de instalação é definida pela opção "--prefix"; a opção "--
exec-prefix" não é suportada no Windows, o que significa que módulos
Python puros e módulos de extensão são instalados no mesmo local. Os
arquivos são instalados da seguinte forma:

+-----------------+------------------------------------------------------------+
| Tipo de arquivo | Diretório de instalação                                    |
|=================|============================================================|
| módulos         | "*prefix*\Lib\site-packages"                               |
+-----------------+------------------------------------------------------------+
| scripts         | "*prefix*\Scripts"                                         |
+-----------------+------------------------------------------------------------+
| dados           | "*prefix*"                                                 |
+-----------------+------------------------------------------------------------+
| cabeçalhos do C | "*prefix*\Include{distname}"                               |
+-----------------+------------------------------------------------------------+


Instalação personalizada
========================

Às vezes, os esquemas de instalação alternativos descritos na seção
Instalação alternativa simplesmente não fazem o que você quer. Você
pode querer ajustar apenas um ou dois diretórios enquanto mantém tudo
sob o mesmo diretório base, ou você pode querer redefinir
completamente o esquema de instalação. Em ambos os casos, você está
criando um *esquema de instalação personalizada*.

Para criar um esquema de instalação personalizada, você começa com um
dos esquemas alternativos e substitui alguns dos diretórios de
instalação usados para os vários tipos de arquivos, usando estas
opções:

+------------------------+-------------------------+
| Tipo de arquivo        | Opção de substituição   |
|========================|=========================|
| módulos Python         | "--install-purelib"     |
+------------------------+-------------------------+
| módulos de extensão    | "--install-platlib"     |
+------------------------+-------------------------+
| todos os módulos       | "--install-lib"         |
+------------------------+-------------------------+
| scripts                | "--install-scripts"     |
+------------------------+-------------------------+
| dados                  | "--install-data"        |
+------------------------+-------------------------+
| cabeçalhos do C        | "--install-headers"     |
+------------------------+-------------------------+

Essas opções de substituição podem ser relativas, absolutas ou
explicitamente definidas em termos de um dos diretórios base da
instalação. (Existem dois diretórios básicos de instalação, e eles são
normalmente os mesmos -- eles só diferem quando você usa o "esquema
prefixo" do Unix e fornece opções diferentes de "--prefix" e "--exec-
prefix"; usar "--install-lib" irá substituir os valores calculados ou
fornecidos para "--install-purelib" e "--install-platlib", e é
recomendado para esquemas que não fazem diferença entre Python e
módulos de extensão.)

Por exemplo, digamos que você esteja instalando uma distribuição de
módulo em seu diretório pessoal no Unix -- mas deseja que os scripts
estejam em "~/scripts" em vez de "~/bin". Como você pode esperar, você
pode substituir este diretório com a opção "--install-scripts"; neste
caso, faz mais sentido fornecer um caminho relativo, que será
interpretado em relação ao diretório base da instalação (seu diretório
home, neste caso):

   python setup.py install --home=~ --install-scripts=scripts

Outro exemplo Unix: suponha que sua instalação Python foi construída e
instalada com um prefixo de "/usr/local/python", então sob uma
instalação padrão os scripts irão acabar em "/usr/local/python/bin".
Se você os quiser em "/usr/local/bin" em vez disso, você deve fornecer
este diretório absoluto para a opção "--install-scripts"

   python setup.py install --install-scripts=/usr/local/bin

(Isso executa uma instalação usando o "esquema prefixo", onde o
prefixo é com o que seu interpretador Python foi instalado --
"/usr/local/python" neste caso.)

Se você mantém o Python no Windows, pode querer que os módulos de
terceiros fiquem em um subdiretório de "*prefix*", ao invés do próprio
"*prefix*". Isso é quase tão fácil quanto personalizar o diretório de
instalação do script -- você apenas tem que lembrar que há dois tipos
de módulos com os quais se preocupar, Python e módulos de extensão,
que podem ser convenientemente controlados por uma opção:

   python setup.py install --install-lib=Site

O diretório de instalação especificado é relativo a "*prefix*".
Obviamente, você também deve garantir que esse diretório esteja no
caminho de pesquisa do módulo do Python, por exemplo, colocando um
arquivo ".pth" em um diretório de site (consulte "site"). Veja a seção
Modificando o caminho de pesquisa do Python para descobrir como
modificar o caminho de pesquisa do Python.

Se você deseja definir todo um esquema de instalação, basta fornecer
todas as opções do diretório de instalação. A maneira recomendada de
fazer isso é fornecer caminhos relativos; por exemplo, se você deseja
manter todos os arquivos relacionados ao módulo Python em "python" em
seu diretório home, e deseja um diretório separado para cada
plataforma de onde você usa seu diretório inicial, você pode definir o
seguinte esquema de instalação:

   python setup.py install --home=~ \
                           --install-purelib=python/lib \
                           --install-platlib=python/lib.$PLAT \
                           --install-scripts=python/scripts
                           --install-data=python/data

ou, equivalentemente,

   python setup.py install --home=~/python \
                           --install-purelib=lib \
                           --install-platlib='lib.$PLAT' \
                           --install-scripts=scripts
                           --install-data=data

"$PLAT" não é (necessariamente) uma variável de ambiente -- ela será
expandida pelo Distutils conforme ele analisa suas opções de linha de
comando, assim como faz ao analisar seu(s) arquivo(s) de configuração.

Obviamente, especificar todo o esquema de instalação toda vez que você
instalar uma nova distribuição de módulo seria muito tedioso. Assim,
você pode colocar essas opções em seu arquivo de configuração
Distutils (consulte a seção Arquivos de configuração do Distutils):

   [install]
   install-base=$HOME
   install-purelib=python/lib
   install-platlib=python/lib.$PLAT
   install-scripts=python/scripts
   install-data=python/data

ou, equivalentemente,

   [install]
   install-base=$HOME/python
   install-purelib=lib
   install-platlib=lib.$PLAT
   install-scripts=scripts
   install-data=data

Observe que esses dois *não* são equivalentes se você fornecer um
diretório base de instalação diferente ao executar o script de
configuração. Por exemplo,

   python setup.py install --install-base=/tmp

instalaria módulos puros em "/tmp/python/lib" no primeiro caso e em
"/tmp/lib" no segundo caso. (Para o segundo caso, você provavelmente
deseja fornecer uma base de instalação de "/tmp/python".)

Você provavelmente notou o uso de "$HOME" e "$PLAT" na entrada do
arquivo de configuração de amostra. Estas são variáveis de
configuração Distutils, que apresentam uma forte semelhança com
variáveis de ambiente. Na verdade, você pode usar variáveis de
ambiente em arquivos de configuração em plataformas que têm essa
noção, mas os Distutils definem adicionalmente algumas variáveis
extras que podem não estar em seu ambiente, como "$PLAT". (E, claro,
em sistemas que não têm variáveis de ambiente, como Mac OS 9, as
variáveis de configuração fornecidas pelo Distutils são as únicas que
você pode usar.) Consulte a seção Arquivos de configuração do
Distutils para detalhes.

Nota:

  Quando um ambiente virtual é ativado, quaisquer opções que alterem o
  caminho de instalação serão ignoradas de todos os arquivos de
  configuração distutils para evitar a instalação inadvertida de
  projetos fora do ambiente virtual.


Modificando o caminho de pesquisa do Python
-------------------------------------------

Quando o interpretador Python executa uma instrução "import", ele
procura tanto o código Python quanto os módulos de extensão ao longo
de um caminho de busca. Um valor padrão para o caminho é configurado
no binário Python quando o interpretador é construído. Você pode
determinar o caminho importando o módulo "sys" e imprimindo o valor de
"sys.path".

   $ python
   Python 2.2 (#11, Oct  3 2002, 13:31:27)
   [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import sys
   >>> sys.path
   ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
    '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
    '/usr/local/lib/python2.3/site-packages']
   >>>

A string nula em "sys.path" representa o diretório de trabalho atual.

A convenção esperada para pacotes instalados localmente é colocá-los
no diretório "*...*/site-packages/", mas você pode querer instalar
módulos Python em algum diretório arbitrário. Por exemplo, seu site
pode ter uma convenção de manter todos os softwares relacionados ao
servidor da web em "/www". Módulos add-on Python podem então pertencer
a "/www/python", e para importá-los, este diretório deve ser
adicionado a "sys.path". Existem várias maneiras de adicionar o
diretório.

A maneira mais conveniente é adicionar um arquivo de configuração de
caminho a um diretório que já está no caminho do Python, geralmente
para o diretório ".../site-packages/". Os arquivos de configuração de
caminho têm uma extensão de ".pth", e cada linha deve conter um único
caminho que será anexado a "sys.path". (Como os novos caminhos são
anexados a "sys.path", os módulos nos diretórios adicionados não
substituirão os módulos padrão. Isso significa que você não pode usar
este mecanismo para instalar versões fixas de módulos padrão.)

Os caminhos podem ser absolutos ou relativos, nesse caso eles são
relativos ao diretório que contém o arquivo ".pth". Veja a
documentação do módulo "site" para mais informações.

Uma maneira um pouco menos conveniente é editar o arquivo  "site.py"
na biblioteca padrão do Python e modificar "sys.path". "site.py" é
importado automaticamente quando o interpretador Python é executado, a
menos que a opção "-S" seja fornecida para suprimir este
comportamento. Portanto, você pode simplesmente editar "site.py" e
adicionar duas linhas a ele:

   import sys
   sys.path.append('/www/python/')

However, if you reinstall the same minor version of Python (perhaps
when upgrading from 2.2 to 2.2.2, for example) "site.py" will be
overwritten by the stock version.  You'd have to remember that it was
modified and save a copy before doing the installation.

Existem duas variáveis de ambiente que podem modificar "sys.path".
"PYTHONHOME" define um valor alternativo para o prefixo da instalação
do Python. Por exemplo, se "PYTHONHOME" estiver definida como
"/www/python", o caminho de pesquisa será definido como "['',
'/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2',
...]".

A variável "PYTHONPATH" pode ser definida como uma lista de caminhos
que serão adicionados ao início de "sys.path". Por exemplo, se
"PYTHONPATH" estiver definida como "/www/python:/opt/py", o caminho de
pesquisa começará com "['/www/python', '/opt/py']". (Observe que os
diretórios devem existir para serem adicionados ao "sys.path"; o
módulo "site" remove caminhos que não existem.)

Finalmente, "sys.path" é apenas uma lista Python regular, então
qualquer aplicação Python pode modificá-la adicionando ou removendo
entradas.


Arquivos de configuração do Distutils
=====================================

Conforme mencionado acima, você pode usar os arquivos de configuração
do Distutils para registrar preferências pessoais ou do site para
qualquer opção do Distutils. Ou seja, qualquer opção para qualquer
comando pode ser armazenada em um de dois ou três (dependendo da sua
plataforma) arquivos de configuração, que serão consultados antes que
a linha de comando seja analisada. Isso significa que os arquivos de
configuração sobrescreverão os valores padrão e a linha de comando,
por sua vez, sobrescreverá os arquivos de configuração. Além disso, se
vários arquivos de configuração se aplicarem, os valores dos arquivos
"anteriores" serão substituídos pelos arquivos "posteriores".


Localização e nomes dos arquivos de configuração
------------------------------------------------

The names and locations of the configuration files vary slightly
across platforms.  On Unix and macOS, the three configuration files
(in the order they are processed) are:

+----------------+------------------------------------------------------------+---------+
| Tipo de        | Localização e nome de arquivo                              | Notas   |
| arquivo        |                                                            |         |
|================|============================================================|=========|
| sistema        | "*prefix*/lib/python*ver*/distutils/distutils.cfg"         | (1)     |
+----------------+------------------------------------------------------------+---------+
| pessoal        | "$HOME/.pydistutils.cfg"                                   | (2)     |
+----------------+------------------------------------------------------------+---------+
| local          | "setup.cfg"                                                | (3)     |
+----------------+------------------------------------------------------------+---------+

E no Windows, os arquivos de configuração são:

+----------------+---------------------------------------------------+---------+
| Tipo de        | Localização e nome de arquivo                     | Notas   |
| arquivo        |                                                   |         |
|================|===================================================|=========|
| sistema        | "*prefix*\Lib\distutils\distutils.cfg"            | (4)     |
+----------------+---------------------------------------------------+---------+
| pessoal        | "%HOME%\pydistutils.cfg"                          | (5)     |
+----------------+---------------------------------------------------+---------+
| local          | "setup.cfg"                                       | (3)     |
+----------------+---------------------------------------------------+---------+

On all platforms, the "personal" file can be temporarily disabled by
passing the "--no-user-cfg" option.

Notas:

1. Estritamente falando, o arquivo de configuração de todo o sistema
   reside no diretório onde os Distutils estão instalados; no Python
   1.6 e posterior no Unix, isso é mostrado. Para Python 1.5.2, o
   Distutils normalmente será instalado em "*prefix*/lib/python1.5
   /site-packages/distutils", então o arquivo de configuração do
   sistema deve ser colocado lá em Python 1.5.2.

2. On Unix, if the "HOME" environment variable is not defined, the
   user's home directory will be determined with the "getpwuid()"
   function from the standard "pwd" module. This is done by the
   "os.path.expanduser()" function used by Distutils.

3. Ou seja, no diretório atual (geralmente a localização do script de
   configuração).

4. (Consulte também a nota (1).) No Python 1.6 e posterior, o "prefixo
   de instalação" padrão do Python é "C:\Python", então o arquivo de
   configuração do sistema é normalmente
   "C:\Python\Lib\distutils\distutils.cfg". No Python 1.5.2, o prefixo
   padrão era "C:\Arquivos de programas\Python", e os Distutils não
   faziam parte da biblioteca padrão -- de forma que o arquivo de
   configuração do sistema seria "C:\Arquivos de
   programas\Python\distutils\distutils.cfg" em uma instalação padrão
   do Python 1.5.2 no Windows.

5. No Windows, Se a variável de ambiente "HOME" não estiver definida,
   "USERPROFILE", então "HOMEDRIVE" e, por fim, "HOMEPATH" serão
   tentados. Isso é feito pela função "os.path.expanduser()" usada
   pelo Distutils.


Sintaxe dos arquivos de configuração
------------------------------------

The Distutils configuration files all have the same syntax.  The
config files are grouped into sections.  There is one section for each
Distutils command, plus a "global" section for global options that
affect every command.  Each section consists of one option per line,
specified as "option=value".

For example, the following is a complete config file that just forces
all commands to run quietly by default:

   [global]
   verbose=0

If this is installed as the system config file, it will affect all
processing of any Python module distribution by any user on the
current system.  If it is installed as your personal config file (on
systems that support them), it will affect only module distributions
processed by you.  And if it is used as the "setup.cfg" for a
particular module distribution, it affects only that distribution.

You could override the default "build base" directory and make the
**build*** commands always forcibly rebuild all files with the
following:

   [build]
   build-base=blib
   force=1

which corresponds to the command-line arguments

   python setup.py build --build-base=blib --force

except that including the **build** command on the command-line means
that command will be run.  Including a particular command in config
files has no such implication; it only means that if the command is
run, the options in the config file will apply.  (Or if other commands
that derive values from it are run, they will use the values in the
config file.)

You can find out the complete list of options for any command using
the "--help" option, e.g.:

   python setup.py build --help

and you can find out the complete list of global options by using "--
help" without a command:

   python setup.py --help

See also the "Reference" section of the "Distributing Python Modules"
manual.


Building Extensions: Tips and Tricks
====================================

Whenever possible, the Distutils try to use the configuration
information made available by the Python interpreter used to run the
"setup.py" script. For example, the same compiler and linker flags
used to compile Python will also be used for compiling extensions.
Usually this will work well, but in complicated situations this might
be inappropriate.  This section discusses how to override the usual
Distutils behaviour.


Tweaking compiler/linker flags
------------------------------

Compiling a Python extension written in C or C++ will sometimes
require specifying custom flags for the compiler and linker in order
to use a particular library or produce a special kind of object code.
This is especially true if the extension hasn't been tested on your
platform, or if you're trying to cross-compile Python.

In the most general case, the extension author might have foreseen
that compiling the extensions would be complicated, and provided a
"Setup" file for you to edit.  This will likely only be done if the
module distribution contains many separate extension modules, or if
they often require elaborate sets of compiler flags in order to work.

A "Setup" file, if present, is parsed in order to get a list of
extensions to build.  Each line in a "Setup" describes a single
module.  Lines have the following structure:

   module ... [sourcefile ...] [cpparg ...] [library ...]

Let's examine each of the fields in turn.

* *module* is the name of the extension module to be built, and should
  be a valid Python identifier.  You can't just change this in order
  to rename a module (edits to the source code would also be needed),
  so this should be left alone.

* *sourcefile* is anything that's likely to be a source code file, at
  least judging by the filename.  Filenames ending in ".c" are assumed
  to be written in C, filenames ending in ".C", ".cc", and ".c++" are
  assumed to be C++, and filenames ending in ".m" or ".mm" are assumed
  to be in Objective C.

* *cpparg* is an argument for the C preprocessor,  and is anything
  starting with "-I", "-D", "-U" or "-C".

* *library* is anything ending in ".a" or beginning with "-l" or "-L".

If a particular platform requires a special library on your platform,
you can add it by editing the "Setup" file and running "python
setup.py build". For example, if the module defined by the line

   foo foomodule.c

must be linked with the math library "libm.a" on your platform, simply
add "-lm" to the line:

   foo foomodule.c -lm

Arbitrary switches intended for the compiler or the linker can be
supplied with the "-Xcompiler" *arg* and "-Xlinker" *arg* options:

   foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

The next option after "-Xcompiler" and "-Xlinker" will be appended to
the proper command line, so in the above example the compiler will be
passed the "-o32" option, and the linker will be passed "-shared".  If
a compiler option requires an argument, you'll have to supply multiple
"-Xcompiler" options; for example, to pass "-x c++" the "Setup" file
would have to contain "-Xcompiler -x -Xcompiler c++".

Compiler flags can also be supplied through setting the "CFLAGS"
environment variable.  If set, the contents of "CFLAGS" will be added
to the compiler flags specified in the  "Setup" file.


Using non-Microsoft compilers on Windows
----------------------------------------


Borland/CodeGear C++
~~~~~~~~~~~~~~~~~~~~

This subsection describes the necessary steps to use Distutils with
the Borland C++ compiler version 5.5.  First you have to know that
Borland's object file format (OMF) is different from the format used
by the Python version you can download from the Python or ActiveState
web site.  (Python is built with Microsoft Visual C++, which uses COFF
as the object file format.) For this reason you have to convert
Python's library "python25.lib" into the Borland format.  You can do
this as follows:

   coff2omf python25.lib python25_bcpp.lib

The "coff2omf" program comes with the Borland compiler.  The file
"python25.lib" is in the "Libs" directory of your Python installation.
If your extension uses other libraries (zlib, ...) you have to convert
them too.

The converted files have to reside in the same directories as the
normal libraries.

How does Distutils manage to use these libraries with their changed
names?  If the extension needs a library (eg. "foo") Distutils checks
first if it finds a library with suffix "_bcpp" (eg. "foo_bcpp.lib")
and then uses this library.  In the case it doesn't find such a
special library it uses the default name ("foo.lib".) [1]

To let Distutils compile your extension with Borland C++ you now have
to type:

   python setup.py build --compiler=bcpp

If you want to use the Borland C++ compiler as the default, you could
specify this in your personal or system-wide configuration file for
Distutils (see section Arquivos de configuração do Distutils.)

Ver também:

  C++Builder Compiler
     Information about the free C++ compiler from Borland, including
     links to the download pages.

  Creating Python Extensions Using Borland's Free Compiler
     Document describing how to use Borland's free command-line C++
     compiler to build Python.


GNU C / Cygwin / MinGW
~~~~~~~~~~~~~~~~~~~~~~

This section describes the necessary steps to use Distutils with the
GNU C/C++ compilers in their Cygwin and MinGW distributions. [2] For a
Python interpreter that was built with Cygwin, everything should work
without any of these following steps.

Not all extensions can be built with MinGW or Cygwin, but many can.
Extensions most likely to not work are those that use C++ or depend on
Microsoft Visual C extensions.

To let Distutils compile your extension with Cygwin you have to type:

   python setup.py build --compiler=cygwin

and for Cygwin in no-cygwin mode [3] or for MinGW type:

   python setup.py build --compiler=mingw32

If you want to use any of these options/compilers as default, you
should consider writing it in your personal or system-wide
configuration file for Distutils (see section Arquivos de configuração
do Distutils.)


Older Versions of Python and MinGW
""""""""""""""""""""""""""""""""""

The following instructions only apply if you're using a version of
Python inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with
binutils-2.13.90-20030111-1).

These compilers require some special libraries.  This task is more
complex than for Borland's C++, because there is no program to convert
the library.  First you have to create a list of symbols which the
Python DLL exports. (You can find a good program for this task at htt
ps://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/).

   pexports python25.dll >python25.def

The location of an installed "python25.dll" will depend on the
installation options and the version and language of Windows.  In a
"just for me" installation, it will appear in the root of the
installation directory.  In a shared installation, it will be located
in the system directory.

Then you can create from these information an import library for gcc.

   /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

The resulting library has to be placed in the same directory as
"python25.lib". (Should be the "libs" directory under your Python
installation directory.)

If your extension uses other libraries (zlib,...) you might  have to
convert them too. The converted files have to reside in the same
directories as the normal libraries do.

Ver também:

  Building Python modules on MS Windows platform with MinGW
     Information about building the required libraries for the MinGW
     environment.

-[ Notas de rodapé ]-

[1] This also means you could replace all existing COFF-libraries with
    OMF-libraries of the same name.

[2] Check https://www.sourceware.org/cygwin/ for more information

[3] Then you have no POSIX emulation available, but you also don't
    need "cygwin1.dll".
