--- title: Capítulo 3. Port Rápido prev: books/porters-handbook/new-port next: books/porters-handbook/slow-porting showBookMenu: true weight: 3 params: path: "/books/porters-handbook/quick-porting/" --- [[quick-porting]] = Port Rápido :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 3 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Esta seção descreve como criar rapidamente um novo port. Para aplicativos em que esse método rápido não for adequado, o processo "Slow Porting" está descrito no crossref:slow-porting[slow-porting,Port Lento]. Primeiro, obtenha o tarball original e coloque-o em `DISTDIR`, que por padrão é o diretório [.filename]#/usr/ports/distfiles#. [NOTE] ==== Estas etapas assumem que o software foi compilado de forma simples (out-of-the-box). Em outras palavras, não foi necessária absolutamente nenhuma mudança para o aplicativo funcionar em um sistema FreeBSD. Se alguma coisa teve que ser alterada, por favor consulte o crossref:slow-porting[slow-porting,Port Lento]. ==== [NOTE] ==== Recomenda-se definir a variável `DEVELOPER` do man:make[1] em [.filename]#/etc/make.conf# antes de começar o trabalho com os ports. [source,shell] .... # echo DEVELOPER=yes >> /etc/make.conf .... Esta configuração habilita o "modo de desenvolvedor" que exibe avisos sobre a descontinuidade de comandos e ativa algumas verificações de qualidade adicionais nas execuções do comando `make`. ==== [[porting-makefile]] == Escrevendo o [.filename]#Makefile# O [.filename]#Makefile# mínimo seria algo assim: [.programlisting] .... # $FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $ PORTNAME= oneko DISTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= youremail@example.com COMMENT= Cat chasing a mouse all over the screen .include .... [NOTE] ==== Em alguns casos, o [.filename]#Makefile# de um port existente pode conter linhas adicionais no cabeçalho, como o nome do port e a data em que foi criado. Esta informação adicional foi declarada obsoleta e está sendo eliminada. ==== Tente entender o exemplo. Não se preocupe com o conteúdo da linha `$FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $`, ela será preenchida automaticamente pelo Subversion quando o port for importado para nossa árvore de ports principais. Um exemplo mais detalhado é mostrado na seção <>. [[porting-desc]] == Escrevendo os Arquivos de Descrição Existem dois arquivos de descrição que são necessários para qualquer port, independente deles estarem empacotados ou não. Eles são o [.filename]#pkg-descr# e o [.filename]#pkg-plist#. Seus prefixos [.filename]#pkg-# distingue-os de outros arquivos. [[porting-pkg-descr]] === [.filename]#pkg-descr# Esta é uma descrição mais longa do port. Um ou alguns parágrafos que explicam o que o port faz é suficiente. [NOTE] ==== Isto _não é_ um manual ou uma descrição detalhada sobre como usar ou compilar o port! _Por favor, tenha cuidado ao copiar do [.filename]#README# ou manpage_. Muitas vezes, eles não são uma descrição concisa do port ou estão em um formato estranho. Por exemplo, as páginas de manual têm espaçamento justificado, o que parece particularmente ruim com fontes monoespaçadas. Por outro lado, o conteúdo de [.filename]#pkg-descr# deve ser mais longo que a linha <> do Makefile. Ele deve explicar com mais profundidade o que é o port. ==== Um [.filename]#pkg-descr# bem escrito descreve o port completamente o suficiente para que os usuários não precisem consultar a documentação ou visitar o site para entender o que o software faz, como ele pode ser útil ou quais recursos particularmente legais ​​ele possui. A menção de certos requisitos, como um kit de ferramentas gráfico, dependências pesadas, ambiente de runtime ou linguagens de implementação, ajuda os usuários a decidir se este port funcionará para eles. Inclua uma URL para a página Web oficial. Prefixe _um_ dos sites (escolha o mais comum) com `WWW:` (seguido por um único espaço) para que as ferramentas automatizadas funcionem corretamente. Se a URI é a raiz do site ou diretório, ele deve ser terminado com uma barra. [NOTE] ==== Se a página web listada para um port não estiver disponível, tente pesquisar na Internet primeiro para ver se o site oficial foi movido, foi renomeado ou se está hospedado em outro lugar. ==== Este exemplo mostra como parece o [.filename]#pkg-descr#: [.programlisting] .... This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) WWW: http://www.oneko.org/ .... [[porting-pkg-plist]] === [.filename]#pkg-plist# Este arquivo lista todos os arquivos instalados pelo port. Ele também é chamado de "packing list" (lista de empacotamento) porque o pacote é gerado empacotando os arquivos listados aqui. Os pathnames são relativos ao prefixo de instalação (geralmente [.filename]#/usr/local#). Aqui está um pequeno exemplo: [.programlisting] .... bin/oneko man/man1/oneko.1.gz lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm .... Consulte a manpage do man:pkg-create[8] para detalhes sobre a lista de empacotamento. [NOTE] ==== É recomendado manter todos os nomes de arquivos neste arquivo classificados em ordem alfabética. Isso tornará muito mais fácil verificar as alterações ao atualizar o port. ==== [TIP] ==== Criar uma lista de packing manualmente pode ser uma tarefa muito tediosa. Se o port instalar um grande número de arquivos, <> pode economizar tempo. ==== Há apenas um caso em que o [.filename]#pkg-plist# pode ser omitido de um port. Se o port instalar apenas alguns arquivos, liste-os em `PLIST_FILES`, dentro do [.filename]#Makefile# do port. Por exemplo, poderíamos passar sem o [.filename]#pkg-plist# no port [.filename]#oneko# acima, adicionando estas linhas para no [.filename]#Makefile#: [.programlisting] .... PLIST_FILES= bin/oneko \ man/man1/oneko.1.gz \ lib/X11/app-defaults/Oneko \ lib/X11/oneko/cat1.xpm \ lib/X11/oneko/cat2.xpm \ lib/X11/oneko/mouse.xpm .... [NOTE] ==== Uso de `PLIST_FILES` não deve ser abusado. Ao procurar pela origem de um arquivo, as pessoas geralmente tentam usar o grep através do [.filename]#pkg-plist# nos arquivos na árvore de ports. Listar os arquivos na variável `PLIST_FILES` dentro do [.filename]#Makefile# torna esta busca mais difícil. ==== [TIP] ==== Se um port precisar criar um diretório vazio, ou criar diretórios fora do [.filename]#${PREFIX}# durante a instalação, consulte crossref:plist[plist-dir-cleaning,Limpando Diretórios Vazios] para maiores informações. ==== [TIP] ==== Como `PLIST_FILES` é uma variavel do man:make[1], qualquer entrada com espaços deve ser envolvida por aspas. Por exemplo, se estiver usando palavras-chave descritas em man:pkg-create[8] e na crossref:plist[plist-keywords,Expandindo a Lista de Pacotes com Keywords], a entrada deve ser citada. [.programlisting] .... PLIST_FILES= "@sample ${ETCDIR}/oneko.conf.sample" .... ==== Mais tarde vamos ver como o [.filename]#pkg-plist# e a `PLIST_FILES` podem ser utilizados para executar <>. [[porting-checksum]] == Criando o Arquivo Checksum Apenas digite `make makesum`. O framework do ports irá gerar automaticamente o [.filename]#distinfo#. Não tente gerar o arquivo manualmente. [[porting-testing]] == Testando o Port Certifique-se de que as regras do port façam exatamente o que é desejado, incluindo o empacotamento do port. Estes são os pontos importantes a serem verificados: * [.filename]#pkg-plist# não contém nada não instalado pelo port. * [.filename]#pkg-plist# contém tudo o que é instalado pelo port. * O port pode ser instalado usando o target `install`. Isso verifica se o script de instalação está funcionando corretamente. * O port pode ser desinstalado adequadamente usando o target `deinstall`. Isso verifica se o script de desinstalação funciona corretamente. * O port só tem acesso aos recursos de rede durante a fase target `fetch`. Isto é importante para os construtores de pacotes, tais como o package:ports-mgmt/poudriere[]. * Certifique-se de que o comando `make package` pode ser executado como um usuário normal (ou seja, não como `root`). Se isso falhar, talvez seja necessário corrigir o software. Veja a crossref:uses[uses-fakeroot,`fakeroot`] e também a crossref:uses[uses-uidfix,`uidfix`]. [.procedure] ==== *Procedure: Ordem Recomendada de Teste* . `make stage` . `make stage-qa` . `make package` . `make install` . `make deinstall` . `make package` (como usuário) ==== Certifique-se de que nenhum aviso é exibido em nenhum dos estágios. Testes automatizados completos podem ser feitos com o package:ports-mgmt/poudriere[] da coleção do Ports, veja a crossref:testing[testing-poudriere,Poudriere] para maiores informações. Ele mantém `jails` onde todas as etapas mostradas acima podem ser testadas sem afetar o estado do sistema host. [[porting-portlint]] == Verificando o Port com `portlint` Por favor, use o `portlint` para ver se o port está de acordo com as nossas diretrizes. O programa package:ports-mgmt/portlint[] faz parte da coleção de ports. Em particular, ele verifica se o <> está correto e se o <> está nomeado apropriadamente. [IMPORTANT] ==== Não siga cegamente a saída do `portlint`. Ela é uma ferramenta de lint estática e às vezes comete erros. ==== [[porting-submitting]] == Enviando o Novo Port Antes de enviar o novo port, leia <>. Uma vez feliz com o port, a única coisa que resta é colocá-lo na árvore principal do FreeBSD e deixar todo mundo feliz também. [IMPORTANT] ==== Nós não precisamos do diretório [.filename]#work# ou do pacote [.filename]#pkgname.tgz#, então exclua-os agora. ==== Em seguida, crie um man:patch[1]. Assumindo que o port é chamado `oneko` e está na categoria `games`. [[porting-submitting-diff]] .Criando um [.filename]#.diff# para um Novo Port [example] ==== Adicione todos os arquivos com `svn add`. Utilize o `cd` e vá para a base da árvore de ports, para que os caminhos completos dos arquivos alterados sejam incluídos no diff, então gere o diff com `svn diff`. Por exemplo: [source,shell] .... % svn add . % cd ../.. % svn diff games/oneko > oneko.diff .... [IMPORTANT] ====== Para ser mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de ports, por favor, gere o [.filename]#.diff# da base da sua árvore de ports. ====== ==== Envie o [.filename]#oneko.diff# com o https://bugs.freebsd.org/submit/[formulário de submissão de bugs]. Use product "Ports & Packages", component "Individual Port(s)" e siga as diretrizes mostradas lá. Adicione uma breve descrição do programa ao campo Description do PR (talvez uma versão curta do `COMMENT`), e lembre-se de adicionar o [.filename]#oneko.diff# como um anexo. [NOTE] ==== Dar uma boa descrição no resumo do relatório de problema facilita muito o trabalho dos commiters de ports. Preferimos algo como "New port: `__category/portname breve descrição do port__`" para novos ports. Usar este esquema torna mais fácil e rápido começar o trabalho para fazer o commit de um novo port. ==== Depois de enviar o port, por favor, seja paciente. O tempo necessário para incluir um novo port no FreeBSD pode variar de alguns dias até alguns meses. Um formulário simples de pesquisa no banco de dados do Relatório de Problemas está disponível em https://bugs.freebsd.org/bugzilla/query.cgi[]. Para obter uma listagem dos PRs _abertos_ para os ports, selecione _Open_ e _Ports & Packages_ no formulário de pesquisa, clique em btn:[Search]. Depois de analisar o novo port, nós responderemos se necessário, e iremos adicioná-lo a árvore. O nome do remetente também será adicionado à lista de extref:{contributors}[Contribuidores Adicionais do FreeBSD, contrib-additional] e outros arquivos. Também é possível enviar ports usando um arquivo man:shar[1]. Usando o exemplo anterior com o port `oneko` acima. [[porting-submitting-shar]] .Criando um [.filename]#.shar# para um Novo Port [example] ==== vá para o diretório acima, onde o diretório do port está localizado, e use `tar` para criar o arquivo shar: [source,shell] .... % cd .. % tar cf oneko.shar --format shar oneko .... ==== [.filename]#oneko.shar# pode ser enviado da mesma maneira que [.filename]#oneko.diff# acima.