Date: Sun, 21 Oct 2018 23:53:44 +0000 (UTC) From: Edson Brandi <ebrandi@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r52397 - in head/pt_BR.ISO8859-1/books: . porters-handbook Message-ID: <201810212353.w9LNriEW062019@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: ebrandi Date: Sun Oct 21 23:53:43 2018 New Revision: 52397 URL: https://svnweb.freebsd.org/changeset/doc/52397 Log: pt_BR.ISO8859-1/books/porters-handbook: New pt_BR translation into .po format - content synchronized with en_US document (rev 52124) - book.xml converted to .po - .po file was translated to pt_BR - .po and .xml file has been set to UTF-8 encoding - information about volunteers who translated and/or revised the document was added to the header of the .po file. Approved by: gabor (mentor, implicit) Obtained from: The FreeBSD Brazilian Portuguese Documentation Project Added: head/pt_BR.ISO8859-1/books/porters-handbook/ head/pt_BR.ISO8859-1/books/porters-handbook/Makefile (contents, props changed) head/pt_BR.ISO8859-1/books/porters-handbook/book.xml (contents, props changed) head/pt_BR.ISO8859-1/books/porters-handbook/pt_BR.po (contents, props changed) Modified: head/pt_BR.ISO8859-1/books/Makefile Modified: head/pt_BR.ISO8859-1/books/Makefile ============================================================================== --- head/pt_BR.ISO8859-1/books/Makefile Sun Oct 21 16:01:09 2018 (r52396) +++ head/pt_BR.ISO8859-1/books/Makefile Sun Oct 21 23:53:43 2018 (r52397) @@ -8,6 +8,7 @@ SUBDIR+= dev-model SUBDIR+= faq SUBDIR+= fdp-primer +SUBDIR+= porters-handbook DOC_PREFIX?= ${.CURDIR}/../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: head/pt_BR.ISO8859-1/books/porters-handbook/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/pt_BR.ISO8859-1/books/porters-handbook/Makefile Sun Oct 21 23:53:43 2018 (r52397) @@ -0,0 +1,50 @@ +# +# $FreeBSD$ +# +# The FreeBSD Documentation Project +# The FreeBSD Brazilian Portuguese Documentation Project +# +# Build the FreeBSD Porter's Handbook. +# + +MAINTAINER=ebrandi@FreeBSD.org + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# XML content +SRCS= book.xml + +# Images from the cross-document image library +IMAGES_LIB+= callouts/1.png +IMAGES_LIB+= callouts/2.png +IMAGES_LIB+= callouts/3.png +IMAGES_LIB+= callouts/4.png +IMAGES_LIB+= callouts/5.png +IMAGES_LIB+= callouts/6.png +IMAGES_LIB+= callouts/7.png +IMAGES_LIB+= callouts/8.png +IMAGES_LIB+= callouts/9.png +IMAGES_LIB+= callouts/10.png +IMAGES_LIB+= callouts/11.png +IMAGES_LIB+= callouts/12.png +IMAGES_LIB+= callouts/13.png +IMAGES_LIB+= callouts/14.png +IMAGES_LIB+= callouts/15.png +IMAGES_LIB+= callouts/16.png +IMAGES_LIB+= callouts/17.png +IMAGES_LIB+= callouts/18.png +IMAGES_LIB+= callouts/19.png +IMAGES_LIB+= callouts/20.png +IMAGES_LIB+= callouts/21.png + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +SYMLINKS= ${DESTDIR} index.html handbook.html + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/pt_BR.ISO8859-1/books/porters-handbook/book.xml Sun Oct 21 23:53:43 2018 (r52397) @@ -0,0 +1,23177 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--><!ENTITY % chapters SYSTEM "chapters.ent"> +<!-- + Creates entities for each chapter in the Porters Handbook. Each entity + is named chap.foo, where foo is the value of the id attribute on that + chapter, and corresponds to the name of the directory in which that + chapter's .xml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $FreeBSD$ +--><!ENTITY chap.porting-why SYSTEM "porting-why/chapter.xml"> +<!ENTITY chap.new-port SYSTEM "new-port/chapter.xml"> +<!ENTITY chap.quick-porting SYSTEM "quick-porting/chapter.xml"> +<!ENTITY chap.slow-porting SYSTEM "slow-porting/chapter.xml"> +<!ENTITY chap.makefiles SYSTEM "makefiles/chapter.xml"> +<!ENTITY chap.special SYSTEM "special/chapter.xml"> +<!ENTITY chap.flavors SYSTEM "flavors/chapter.xml"> +<!ENTITY chap.plist SYSTEM "plist/chapter.xml"> +<!ENTITY chap.pkg-files SYSTEM "pkg-files/chapter.xml"> +<!ENTITY chap.testing SYSTEM "testing/chapter.xml"> +<!ENTITY chap.upgrading SYSTEM "upgrading/chapter.xml"> +<!ENTITY chap.security SYSTEM "security/chapter.xml"> +<!ENTITY chap.porting-dads SYSTEM "porting-dads/chapter.xml"> +<!ENTITY chap.porting-samplem SYSTEM "porting-samplem/chapter.xml"> +<!ENTITY chap.order SYSTEM "order/chapter.xml"> +<!ENTITY chap.keeping-up SYSTEM "keeping-up/chapter.xml"> +<!ENTITY chap.uses SYSTEM "uses/chapter.xml"> +<!ENTITY chap.versions SYSTEM "versions/chapter.xml"> +]> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:its="http://www.w3.org/2005/11/its" version="5.0" xml:lang="pt_BR"> + + <info> + <title>FreeBSD Porter's Handbook</title> + + <authorgroup> + <author><orgname>Projeto de Documentação do FreeBSD</orgname></author> + </authorgroup> + + <pubdate>$FreeBSD$</pubdate> + + <copyright><year>2000</year><year>2001</year><year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year><year>2007</year><year>2008</year><year>2009</year><year>2010</year><year>2011</year><year>2012</year><year>2013</year><year>2014</year><year>2015</year><year>2016</year><year>2017</year><year>2018</year><holder role="mailto:doc@FreeBSD.org">Projeto de Documentação do FreeBSD</holder></copyright> + + +<legalnotice xml:id="legalnotice"> + <title>Copyright</title> + + <para>Redistribution and use in source (XML DocBook) and 'compiled' forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:</para> + + <orderedlist> + <listitem> + <para>Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.</para> + </listitem> + + <listitem> + <para>Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</para> + </listitem> + </orderedlist> + + <important> + <para>THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para> + </important> +</legalnotice> + + + <legalnotice xml:id="trademarks" role="trademarks"> + <para>FreeBSD is a registered trademark of the FreeBSD Foundation.</para> + <para>UNIX is a registered trademark of The Open Group in the United States and other countries.</para> + <para>Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice, SunOS and VirtualBox are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.</para> + <para>Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the <quote>™</quote> or the <quote>®</quote> symbol.</para> + </legalnotice> + + <releaseinfo>$FreeBSD$</releaseinfo> + </info> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="why-port"> + + <title>Introdução</title> + + <para>A Coleção de Ports do FreeBSD é a maneira como quase todo mundo instala aplicativos ("ports") no FreeBSD. Como tudo no FreeBSD, é principalmente um esforço voluntário. É importante ter isso em mente ao ler este documento.</para> + + <para>No FreeBSD, qualquer um pode enviar um novo port ou ser voluntário para manter um port que esteja sem mantenedor. Nenhum privilégio de commit é necessário.</para> +</chapter> + + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter version="5.0" xml:id="own-port"> + + <title>Criando um Novo Port</title> + + <para>Interessado em fazer um novo port ou atualizar os ports existentes? Ótimo!</para> + + <para>O que segue são algumas instruções para criar um novo port para o FreeBSD. Para atualizar um port existente, leia este documento e depois leia o <xref linkend="port-upgrading"/>.</para> + + <para>Quando este documento não for suficientemente detalhado, consulte <filename>/usr/ports/Mk/bsd.port.mk</filename>, que é incluído por todos os <filename>Makefile</filename>s dos ports. Mesmo aqueles que não estão hackeando os <filename>Makefile</filename>s diariamente podem ganhar muito conhecimento com isso. Além disso, perguntas específicas podem ser enviadas à <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">; Lista de discussão do ports do FreeBSD</link>.</para> + + <note> + <para>Apenas uma fração das variáveis (<varname><replaceable>VAR</replaceable></varname>) que podem ser sobrepostas são mencionados neste documento. A maioria (se não todas) estão documentadas no início do <filename>/usr/ports/Mk/bsd.port.mk</filename>; as outras provavelmente deveriam estar também. Observe que esse arquivo usa uma configuração de tabulação não padrão: O <application>Emacs</application> e o <application>Vim</application> irão reconhecer a configuração ao carregar o arquivo. Ambos <citerefentry><refentrytitle>vi</refentrytitle><manvolnum>1</manvolnum></citerefentry> e <citerefentry><refentrytitle>ex</refentrytitle><manvolnum>1</manvolnum></citerefentry> podem ser configurados para usar o valor correto digitando <command>:set tabstop=4</command> uma vez que o arquivo foi carregado.</para> + </note> + + <para>Procurando algo fácil para começar? Dê uma olhada na <link xlink:href="https://wiki.freebsd.org/WantedPorts">lista de ports desejados</link> e veja se você pode trabalhar em um (ou mais de um).</para> +</chapter> + + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="quick-porting"> + + <title>Port Rápido</title> + + <para>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 <quote>Slow Porting</quote> está descrito no <xref linkend="slow-porting"/>.</para> + + <para>Primeiro, obtenha o tarball original e coloque-o em <varname>DISTDIR</varname>, que por padrão é o diretório <filename>/usr/ports/distfiles</filename>.</para> + + <note> + <para>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 <xref linkend="slow-porting"/>.</para> + </note> + + <note> + <para>Recomenda-se definir a variável <varname>DEVELOPER</varname> do <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> em <filename>/etc/make.conf</filename> antes de começar o trabalho com os ports.</para> + + <screen><prompt>#</prompt> <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen> + + <para>Esta configuração habilita o <quote>modo de desenvolvedor</quote> que exibe avisos sobre a descontinuidade de comandos e ativa algumas verificações de qualidade adicionais nas execuções do comando <command>make</command>.</para> + </note> + + <sect1 xml:id="porting-makefile"> + <title>Escrevendo o <filename>Makefile</filename></title> + + <para>O <filename>Makefile</filename> mínimo seria algo assim:</para> + + <programlisting># $FreeBSD$ + +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 <bsd.port.mk></programlisting> + + <note> + <para>Em alguns casos, o <filename>Makefile</filename> 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.</para> + </note> + + <para>Tente entender o exemplo. Não se preocupe com o conteúdo da linha <literal>$FreeBSD$</literal>, ela será preenchida automaticamente pelo <application>Subversion</application> quando o port for importado para nossa árvore de ports principais. Um exemplo mais detalhado é mostrado na seção <link linkend="porting-samplem">exemplo de Makefile</link>.</para> + </sect1> + + <sect1 xml:id="porting-desc"> + <title>Escrevendo os Arquivos de Descrição</title> + + <para>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</filename> e o <filename>pkg-plist</filename>. Seus prefixos <filename>pkg-</filename> distingue-os de outros arquivos.</para> + + <sect2 xml:id="porting-pkg-descr"> + <title><filename>pkg-descr</filename></title> + + <para>Esta é uma descrição mais longa do port. Um ou alguns parágrafos que explicam o que o port faz é suficiente.</para> + + <note> + <para>Isto <emphasis>não é</emphasis> um manual ou uma descrição detalhada sobre como usar ou compilar o port! <emphasis>Por favor, tenha cuidado ao copiar do <filename>README</filename> ou manpage </emphasis>. 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.</para> + + <para>Por outro lado, o conteúdo de <filename>pkg-descr</filename> deve ser mais longo que a linha <link linkend="makefile-comment"><varname>COMMENT</varname></link> do Makefile. Ele deve explicar com mais profundidade o que é o port.</para> + </note> + + <para>Um <filename>pkg-descr</filename> 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.</para> + + <para>Inclua uma URL para a página Web oficial. Prefixe <emphasis>um</emphasis> dos sites (escolha o mais comum) com <literal>WWW:</literal> (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.</para> + + <note> + <para>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.</para> + </note> + + <para>Este exemplo mostra como parece o <filename>pkg-descr</filename>:</para> + + <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/</programlisting>; + </sect2> + + <sect2 xml:id="porting-pkg-plist"> + <title><filename>pkg-plist</filename></title> + + <para>Este arquivo lista todos os arquivos instalados pelo port. Ele também é chamado de <quote>packing list</quote> (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</filename>).</para> + + <para>Aqui está um pequeno exemplo:</para> + + <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</programlisting> + + <para>Consulte a manpage do <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> para detalhes sobre a lista de empacotamento.</para> + + <note> + <para>É 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.</para> + </note> + + <tip> + <para>Criar uma lista de packing manualmente pode ser uma tarefa muito tediosa. Se o port instalar um grande número de arquivos, <link linkend="plist-autoplist">criar a lista de empacotamento automaticamente</link> pode economizar tempo.</para> + </tip> + + <para>Há apenas um caso em que o <filename>pkg-plist</filename> pode ser omitido de um port. Se o port instalar apenas alguns arquivos, liste-os em <varname>PLIST_FILES</varname>, dentro do <filename>Makefile</filename> do port. Por exemplo, poderíamos passar sem o <filename>pkg-plist</filename> no port <filename>oneko</filename> acima, adicionando estas linhas para no <filename>Makefile</filename>:</para> + + <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</programlisting> + + <note> + <para>Uso de <varname>PLIST_FILES</varname> não deve ser abusado. Ao procurar pela origem de um arquivo, as pessoas geralmente tentam usar o <application>grep</application> através do <filename>pkg-plist</filename> nos arquivos na árvore de ports. Listar os arquivos na variável <varname>PLIST_FILES</varname> dentro do <filename>Makefile</filename> torna esta busca mais difícil.</para> + </note> + + <tip> + <para>Se um port precisar criar um diretório vazio, ou criar diretórios fora do <filename>${PREFIX}</filename> durante a instalação, consulte <xref linkend="plist-dir-cleaning"/> para maiores informações.</para> + </tip> + + <tip> + <para>Como <varname>PLIST_FILES</varname> é uma variavel do <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, qualquer entrada com espaços deve ser envolvida por aspas. Por exemplo, se estiver usando palavras-chave descritas em <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> e na <xref linkend="plist-keywords"/>, a entrada deve ser citada.</para> + + <programlisting>PLIST_FILES= "@sample ${ETCDIR}/oneko.conf.sample"</programlisting> + </tip> + + <para>Mais tarde vamos ver como o <filename>pkg-plist</filename> e a <varname>PLIST_FILES</varname> podem ser utilizados para executar <link linkend="plist">tarefas mais sofisticadas</link>.</para> + </sect2> + </sect1> + + <sect1 xml:id="porting-checksum"> + <title>Criando o Arquivo Checksum</title> + + <para>Apenas digite <command>make makesum</command>. O framework do ports irá gerar automaticamente o <filename>distinfo</filename>. Não tente gerar o arquivo manualmente.</para> + </sect1> + + <sect1 xml:id="porting-testing"> + <title>Testando o Port</title> + + <para>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:</para> + + <itemizedlist> + <listitem> + <para><filename>pkg-plist</filename> não contém nada não instalado pelo port.</para> + </listitem> + + <listitem> + <para><filename>pkg-plist</filename> contém tudo o que é instalado pelo port.</para> + </listitem> + + <listitem> + <para>O port pode ser instalado usando o target <buildtarget>install</buildtarget>. Isso verifica se o script de instalação está funcionando corretamente.</para> + </listitem> + + <listitem> + <para>O port pode ser desinstalado adequadamente usando o target <buildtarget>deinstall</buildtarget>. Isso verifica se o script de desinstalação funciona corretamente.</para> + </listitem> + + <listitem> + <para>O port só tem acesso aos recursos de rede durante a fase target <buildtarget>fetch</buildtarget>. Isto é importante para os construtores de pacotes, tais como o <package role="port">ports-mgmt/poudriere</package>.</para> + </listitem> + + <listitem> + <para>Certifique-se de que o comando <command>make package</command> pode ser executado como um usuário normal (ou seja, não como <systemitem class="username">root</systemitem>). Se isso falhar, talvez seja necessário corrigir o software. Veja a <xref linkend="uses-fakeroot"/> e também a <xref linkend="uses-uidfix"/>.</para> + </listitem> + </itemizedlist> + + <procedure> + <title>Ordem Recomendada de Teste</title> + + <step> + <para><command>make stage</command></para> + </step> + + <step> + <para><command>make check-orphans</command></para> + </step> + + <step> + <para><command>make package</command></para> + </step> + + <step> + <para><command>make install</command></para> + </step> + + <step> + <para><command>make deinstall</command></para> + </step> + + <step> + <para><command>make package</command> (como usuário)</para> + </step> + </procedure> + + <para>Certifique-se de que nenhum aviso é exibido em nenhum dos estágios.</para> + + <para>Testes automatizados completos podem ser feitos com o <package role="port">ports-mgmt/poudriere</package> da coleção do Ports, veja a <xref linkend="testing-poudriere"/> para maiores informações. Ele mantém <literal>jails</literal> onde todas as etapas mostradas acima podem ser testadas sem afetar o estado do sistema host.</para> + </sect1> + + <sect1 xml:id="porting-portlint"> + <title>Verificando o Port com <command>portlint</command></title> + + <para>Por favor, use o <command>portlint</command> para ver se o port está de acordo com as nossas diretrizes. O programa <package role="port">ports-mgmt/portlint</package> faz parte da coleção de ports. Em particular, ele verifica se o <link linkend="porting-samplem">Makefile</link> está correto e se o <link linkend="porting-pkgname">pacote</link> está nomeado apropriadamente.</para> + + <important> + <para>Não siga cegamente a saída do <command>portlint</command>. Ela é uma ferramenta de lint estática e às vezes comete erros.</para> + </important> + </sect1> + + <sect1 xml:id="porting-submitting"> + <title>Enviando o Novo Port</title> + + <para>Antes de enviar o novo port, leia <link linkend="porting-dads">a seção sobre o que fazer e o que não fazer</link>.</para> + + <para>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.</para> + + <important> + <para>Nós não precisamos do diretório <filename>work</filename> ou do pacote <filename>pkgname.tgz</filename>, então exclua-os agora.</para> + </important> + + <para>Em seguida, crie um <citerefentry><refentrytitle>patch</refentrytitle><manvolnum>1</manvolnum></citerefentry> ou um arquivo <citerefentry><refentrytitle>shar</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Assumindo que o port é chamado <literal>oneko</literal> e está na categoria <literal>games</literal>.</para> + + <example xml:id="porting-submitting-diff"> + <title>Criando um <filename>.diff</filename> para um Novo Port.</title> + + <para>Adicione todos os arquivos com <command>svn add</command>. Utilize o <command>cd</command> 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 <command>svn diff</command>. Por exemplo:</para> + + <screen><prompt>%</prompt> <userinput>svn add .</userinput> +<prompt>%</prompt> <userinput>cd ../..</userinput> +<prompt>%</prompt> <userinput>svn diff <replaceable>games/oneko</replaceable> > <replaceable>oneko.diff</replaceable></userinput></screen> + + <important> + <para>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</filename> da base da sua árvore de ports.</para> + </important> + </example> + + <example xml:id="porting-submitting-shar"> + <title>Criando um <filename>.shar</filename> para um Novo Port.</title> + + <para>Utilize o <command>cd</command> e vá para o diretório acima de onde o diretório do port está localizado e use <command>shar</command> para criar o arquivo:</para> + + <screen><prompt>%</prompt> <userinput>cd ..</userinput> +<prompt>%</prompt> <userinput>shar `find <replaceable>oneko</replaceable>` > <replaceable>oneko</replaceable>.shar</userinput></screen> + </example> + + <para>Envie um dos <filename>oneko.shar</filename> ou <filename>oneko.diff</filename> com o <link xlink:href="https://bugs.freebsd.org/submit/">; formulário de submissão de bugs</link>. Use product <quote>Ports & Packages</quote>, component <quote>Individual Port(s)</quote> e siga as diretrizes mostradas lá. Adicione uma breve descrição do programa ao campo Description do PR (talvez uma versão curta do <varname>COMMENT</varname>), e lembre-se de adicionar o <filename>oneko.shar</filename> ou <filename>oneko.diff</filename> como um anexo.</para> + + <note> + <para>Dar uma boa descrição no resumo do relatório de problema facilita muito o trabalho dos commiters de ports. Preferimos algo como <quote>New port: <replaceable>category</replaceable>/<replaceable>portname</replaceable> <replaceable>breve descrição do port</replaceable></quote> 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.</para> + </note> + + <para>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 <link xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi"/></para>; + + <para>Para obter uma listagem dos <acronym>PR</acronym>s <emphasis>abertos</emphasis> para os ports, selecione <emphasis>Open</emphasis> e <emphasis>Ports & Packages</emphasis> no formulário de pesquisa, clique em <guibutton>[ Search ]</guibutton>.</para> + + <para>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 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/contributors/contrib-additional.html">Contribuidores Adicionais do FreeBSD</link> e outros arquivos.</para> + </sect1> +</chapter> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="slow-porting"> + + <title>Port Lento</title> + + <para>Certo, então não foi tão simples e o port precisou de algumas modificações para poder funcionar. Nesta seção, vamos explicar passo a passo como modificá-lo para que funcione com o paradigma do ports.</para> + + <sect1 xml:id="slow-work"> + <title>Como as Coisas Funcionam</title> + + <para>Primeiro, esta é a sequência de eventos que ocorre quando o usuário executa <command>make</command> no diretório do port. Ter o <filename>bsd.port.mk</filename> aberto em outra janela enquanto lê esta seção realmente irá ajudar a entender melhor.</para> + + <para>Mas não se preocupe, não são muitas as pessoas que entendem exatamente como o <filename>bsd.port.mk</filename> funciona...<emphasis>:-)</emphasis></para> + + <procedure> + <step> + <para>O target <buildtarget>fetch</buildtarget> é executado. O target <buildtarget>fetch</buildtarget> é responsável por garantir que o tarball exista localmente em <varname>DISTDIR</varname>. Se o <buildtarget>fetch</buildtarget> não puder encontrar os arquivos necessários no <varname>DISTDIR</varname> ele procurará a URL na variável <varname>MASTER_SITES</varname>, definida no Makefile, assim como nos nossos mirrors FTP nos quais colocamos os distfiles como backup. Em seguida, ele tentará buscar o arquivo de distribuição nomeado com <varname>FETCH</varname>, assumindo que o site solicitante tem acesso direto à Internet. Se isso for bem sucedido, ele salvará o arquivo em <varname>DISTDIR</varname> para uso futuro e continuará.</para> + </step> + + <step> + <para>O target <buildtarget>extract</buildtarget> é executado. Ele procura pelo arquivo de distribuição do port (normalmente um tarball compactado) em <varname>DISTDIR</varname> e irá descompactá-lo em um subdiretório temporário especificado por <varname>WRKDIR</varname> (padrão é <filename>work</filename>) </para> + </step> + + <step> + <para>O target <buildtarget>patch</buildtarget> é executado. Primeiro, quaisquer patches definidos em <varname>PATCHFILES</varname> são aplicados. Segundo, se arquivos de patch nomeados <filename>patch-<replaceable>*</replaceable></filename> forem encontrados em <varname>PATCHDIR</varname> (padrão para o subdiretório <filename>files</filename>), eles serão aplicados neste momento em ordem alfabética.</para> + </step> + + <step> + <para>O target <buildtarget>configure</buildtarget> é executado. Ele pode fazer qualquer uma de muitas coisas diferentes.</para> + + <orderedlist> + <listitem> + <para>Se existir, <filename>scripts/configure</filename> é executado.</para> + </listitem> + + <listitem> + <para>E se <varname>HAS_CONFIGURE</varname> ou <varname>GNU_CONFIGURE</varname> está definido, <filename>WRKSRC/configure </filename>é executado.</para> + </listitem> + </orderedlist> + </step> + + <step> + <para>O target <buildtarget>build</buildtarget> é executado. Ele é responsável por mudar para o diretório de trabalho privado do port (<varname>WRKSRC</varname>) e compila-lo.</para> + </step> + + <step> + <para>O target <buildtarget>stage</buildtarget> é executado. Este coloca o conjunto final de arquivos construídos em um diretório temporário (<varname>STAGEDIR</varname>, Veja <xref linkend="staging"/>). A hierarquia deste diretório espelha a do sistema no qual o pacote será instalado.</para> + </step> + + <step> + <para>O target <buildtarget>package</buildtarget> é executado. Ele cria um pacote usando os arquivos do diretório temporário criado durante o target <buildtarget>stage</buildtarget> e o <filename>pkg-plist</filename> do port.</para> + </step> + + <step> + <para>O target <buildtarget>install</buildtarget> é executado. Este instala o pacote criado durante o target <buildtarget>package</buildtarget> no host.</para> + </step> + </procedure> + + <para>As ações acima são padrão. Além disso, defina os targets <buildtarget>pre-<replaceable>something</replaceable></buildtarget> ou <buildtarget>post-<replaceable>something</replaceable></buildtarget>, ou insira scripts com esses nomes no subdiretório <filename>scripts</filename>, e eles serão executados antes ou depois das ações padrão serem executadas.</para> + + <para>Por exemplo, se houver um target <buildtarget>post-extract</buildtarget> definido no <filename>Makefile</filename> e um arquivo <filename>pre-build</filename> no subdiretório <filename>scripts</filename>, o target <buildtarget>post-extract</buildtarget> será chamado após as ações de extração regulares e <filename>pre-build</filename> será executado antes que as regras de compilação padrão sejam feitas. Recomenda-se usar targets no <filename>Makefile</filename> se as ações forem simples, porque será mais fácil para alguém descobrir que tipo de ação não padrão o port necessita.</para> + + <para>As ações padrão são feitas pelos targets <buildtarget>do-<replaceable>something</replaceable></buildtarget> do <filename>bsd.port.mk</filename>. Por exemplo, os comandos para extrair um port estão no target <buildtarget>do-extract</buildtarget>. Se o target padrão não fizer o trabalho direito, redefina o target <buildtarget>do-<replaceable>something</replaceable></buildtarget> no <filename>Makefile</filename>.</para> + + <note> + <para>O target <quote>principal</quote> (por exemplo, <buildtarget>extract</buildtarget>, <buildtarget>configure</buildtarget>, etc.) fazem nada mais do que certificar-se de que todos os estágios até aquele estão concluídos e chamar os targets ou scripts reais, e eles não pretendem ser alterados. Para consertar a extração, corrija <buildtarget>do-extract</buildtarget>, mas nunca mude a forma como <buildtarget>extract</buildtarget> opera! Além disso, o target <buildtarget>post-deinstall</buildtarget> é inválido e não é executado pela infraestrutura de ports.</para> + </note> + + <para>Agora que o que acontece quando o usuário digita <command>make install</command> é melhor entendido, vamos seguir as etapas recomendadas para criar o port perfeito.</para> + </sect1> + + <sect1 xml:id="slow-sources"> + <title>Obtendo os Fontes Originais</title> + + <para>Obtenha os fontes originais (normalmente) como um tarball compactado (<filename>foo.tar.gz</filename> ou <filename><replaceable>foo</replaceable>.tar.bz2</filename>) e copie-o para <varname>DISTDIR</varname>. Use fontes do <emphasis>mainstream</emphasis> sempre que possível.</para> + + <para>Definir a variável <varname>MASTER_SITES</varname> para refletir onde o tarball original reside. Existem definições abreviadas para a maioria dos sites mainstream em <filename>bsd.sites.mk</filename>. Por favor, use esses sites - e as definições associadas—se for possível, para ajudar a evitar o problema de ter as mesmas informações repetidas várias vezes na base de origem. Como esses sites tendem a mudar com o tempo, isso se torna um pesadelo de manutenção para todos os envolvidos. Veja <xref linkend="makefile-master_sites"/> para detalhes.</para> + + <para>Se não houver nenhum site FTP/HTTP bem conectado à rede ou se puder encontrar apenas sites com formatos irritantemente não-padrão, coloque uma cópia em um servidor FTP ou HTTP confiável (por exemplo, uma home page).</para> + + <para>Se um lugar conveniente e confiável para colocar o distfile não puder ser encontrado, nós podemos <quote>hospedar</quote> em <systemitem>ftp.FreeBSD.org</systemitem>; no entanto, esta é a solução menos preferida. O distfile deve ser colocado em <filename>~/public_distfiles/</filename> da conta <systemitem>freefall</systemitem> de alguém. Peça para a pessoa que for fazer o commit do port para realizer isso. Essa pessoa também irá definir <varname>MASTER_SITES</varname> para <literal>LOCAL/<replaceable>username</replaceable></literal> onde <literal><replaceable>username</replaceable></literal> é o seu login do cluster do FreeBSD.</para> + + <para>Se o distfile do port mudar o tempo todo sem nenhum tipo de atualização de versão pelo autor, considere colocar o distfile em uma página pessoal e liste-a como o <varname>MASTER_SITES</varname> primário. Tente falar com o autor do port para parar de fazer isso; Isso realmente ajuda a estabelecer algum tipo de controle de código-fonte. Hospedar uma versão específica impedirá que os usuários obtenham erros de <errorname>checksum mismatch</errorname>, e também irá reduzir a carga de trabalho dos mantenedores do nosso site FTP. Além disso, se houver apenas um site master para o port, recomenda-se armazenar um backup em uma home page e listá-lo como o <varname>MASTER_SITES</varname> secundário.</para> + + <para>Se o port exigir patches adicionais disponíveis na Internet, baixe-os também e coloque-os em <varname>DISTDIR</varname>. Não se preocupe se eles vierem de um site diferente de onde vem o tarball do código fonte principal, temos uma maneira de lidar com essas situações (veja a descrição <link linkend="porting-patchfiles">PATCHFILES</link> abaixo).</para> + </sect1> + + <sect1 xml:id="slow-modifying"> + <title>Modificando o Port</title> + + <para>Desempacote uma cópia do tarball em um diretório privado e faça as alterações necessárias para que o port compile corretamente sob a versão atual do FreeBSD. <emphasis>Atenção dobrada</emphasis> nessas etapas, pois elas serão necessárias para automatizar o processo em breve. Tudo, incluindo a exclusão, adição ou modificação de arquivos, devem ser realizados usando um script automatizado ou um arquivo patch quando o port estiver finalizado.</para> + + <para>Se o port exigir interação/customização significativa do usuário para compilar ou instalar, dê uma olhada em um dos scripts <application>Configure</application> clássicos de Larry Wall e talvez faça algo semelhante. O objetivo da nova coleção de ports é fazer com que cada port seja <quote>plug-and-play</quote> o quanto possível para o usuário final, usando um mínimo de espaço em disco.</para> + + <note> + <para>A menos que explicitamente declarado, os arquivos de patch, scripts e outros arquivos criados e contribuídos para a coleção de ports do FreeBSD são assumidos como cobertos pelas condições de copyright padrão do BSD.</para> + </note> + </sect1> + + <sect1 xml:id="slow-patch"> + <title>Patching</title> + + <para>Na preparação do port, arquivos que forem adicionados ou alterados podem ser gravados com <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> para posterior inclusão em um <citerefentry><refentrytitle>patch</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Fazer isso com um arquivo típico envolve salvar uma cópia do arquivo original antes de fazer qualquer alteração usando um sufixo <filename>.orig</filename>.</para> + + <screen><prompt>%</prompt> <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen> + + <para>Depois que todas as alterações forem realizadas, <command>cd</command> de volta ao diretório do port. Execute <command>make makepatch</command> para gerar arquivos de patch atualizados no diretório <filename>files</filename>.</para> + + <tip> + <para>Usar <varname>BINARY_ALIAS</varname> para substituir comandos codificados durante a compilação e para evitar patching de arquivos de compilação. Veja <xref linkend="binary-alias"/> para maiores informações.</para> + </tip> + + <sect2 xml:id="slow-patch-rules"> + <title>Regras Gerais para Patching</title> + + <para>Arquivos patch são armazenados em <varname>PATCHDIR</varname>, geralmente <filename>files/</filename>, de onde serão aplicados automaticamente. Todas os patches devem ser relativos ao <varname>WRKSRC</varname>. Tipicamente <varname>WRKSRC</varname> é um subdiretório de <varname>WRKDIR</varname>, o diretório onde o distfile é extraído. Execute <command>make -V WRKSRC</command> para ver o caminho real. Os nomes dos patches devem seguir estas regras:</para> + + <itemizedlist> + <listitem> + <para>Evite ter mais de um patch modificando o mesmo arquivo. Por exemplo, ter os dois <filename>patch-foobar.c</filename> e <filename>patch-foobar.c2</filename> fazendo alterações em <filename>${WRKSRC}/foobar.c</filename> torna-os frágeis e difíceis de serem depurados.</para> + </listitem> + + <listitem> + <para>Ao criar nomes para arquivos de patch, substitua cada underline (<literal>_</literal>) com dois underlines (<literal>__</literal>) e cada barra (<literal>/</literal>) com um underline (<literal>_</literal>). Por exemplo, para corrigir um arquivo chamado <filename>src/freeglut_joystick.c</filename> nomeie o patch correspondente <filename>patch-src_freeglut__joystick.c</filename>. Não nomeie patches como <filename>patch-aa</filename> ou <filename>patch-ab</filename>. Sempre use o caminho e o nome do arquivo nos nomes dos patches. O <command>make makepatch</command> gera automaticamente os nomes corretos.</para> + </listitem> + + <listitem> + <para>Um patch pode modificar vários arquivos se as alterações estiverem relacionadas e o patch tiver o nome apropriado. Por exemplo, <filename>patch-add-missing-stdlib.h</filename>.</para> + </listitem> + + <listitem> + <para>Use apenas caracteres <literal>[-+._ a-zA-Z0-9]</literal> para nomear patches. Em particular, <emphasis>não use <literal>::</literal> como um separador de path, </emphasis> use <literal>_</literal> no lugar.</para> + </listitem> + </itemizedlist> + + + <para>Minimize a quantidade de mudanças de espaço em branco não funcionais em patches. É comum no mundo Open Source para projetos compartilhar grandes quantidades de uma base de código, mas obedecer a regras de recuo e estilo diferentes. Ao usar uma funcionalidade funcional de um projeto para consertar áreas similares em outra, por favor, tenha cuidado: o patch resultante pode estar cheio de mudanças não-funcionais. Ele não só aumenta o tamanho do repositório do ports, mas torna difícil descobrir o que exatamente causou o problema e o que foi alterado em todos.</para> + + <para>Se um arquivo precisar ser excluído, faça-o no target <buildtarget>post-extract</buildtarget> em vez de como parte do patch.</para> + + </sect2> + + <sect2 xml:id="slow-patch-manual"> + <title>Geração Manual de Patches</title> + + <note> + <para>A criação manual de patches geralmente não é necessária. A geração automática de patches, conforme descrito anteriormente nesta seção, é o método preferido. No entanto, patches manuais podem ser necessários ocasionalmente.</para> + </note> + + <para>Patches são salvos em arquivos nomeados como <filename>patch-*</filename> onde <replaceable>*</replaceable> indica o nome do caminho do arquivo que está sendo feito o patch, como <filename>patch-imakefile</filename> ou <filename>patch-src-config.h</filename>.</para> + + <para>Depois que o arquivo foi modificado, <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> é usado para registrar as diferenças entre a versão original e a modificada. <option>-u</option> faz com que o <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> produza diffs <quote>unificados</quote>, a forma preferida.</para> + + <screen><prompt>%</prompt> <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> > patch-<replaceable>pathname-file</replaceable></userinput></screen> + + <para>Ao gerar patches para novos arquivos adicionados, <option>-N</option> é usado para dizer ao <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> para tratar o arquivo original inexistente como se existisse, mas estava vazio:</para> + + <screen><prompt>%</prompt> <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> > patch-<replaceable>pathname-newfile</replaceable></userinput></screen> + + <para>Não adicione Strings RCS <literal>$FreeBSD$</literal> em patches. Quando os patches são adicionados ao repositório <application>Subversion</application> com <command>svn add</command>, a propriedade <literal>fbsd:nokeywords</literal> é definida para <literal>yes</literal> automaticamente para que as keywords no patch não sejam modificadas no commit. A propriedade pode ser adicionada manualmente <command>svn propset fbsd:nokeywords yes <replaceable>files...</replaceable></command>.</para> + + <para>Usar a opção (<option>-r</option>) do <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> para gerar patches é razoável, mas por favor, analise os patches resultantes para se certificar de que não há nenhum lixo desnecessário neles. Em particular, diffs entre dois arquivos de backup, quando o port usa <command>Imake</command> ou GNU <command>configure</command>, etc., diffs de <filename>Makefile</filename>s são desnecessários e devem ser eliminados. Se for necessário editar o <filename>configure.in</filename> e executar o <command>autoconf</command> para regerar o <command>configure</command>, não gere diffs do <command>configure</command> (ele geralmente cresce para algumas milhares de linhas!). Em vez disso, defina <literal>USES=autoreconf</literal> e gere os diffs no <filename>configure.in</filename>.</para> + + </sect2> + + <sect2 xml:id="slow-patch-automatic-replacements"> + <title>Substituições Automáticas Simples</title> + + <para>Substituições simples podem ser realizadas diretamente do <filename>Makefile</filename> do port usando o modo in-loco do <citerefentry><refentrytitle>sed</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Isso é útil quando as alterações usam o valor de uma variável:</para> + + <programlisting>post-patch: + @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting> + + <para>Muitas vezes, o software sendo portado usa a convenção CR/LF nos arquivos fonte. Isso pode causar problemas com correções adicionais, avisos do compilador ou execução de scripts (como <literal>/bin/sh^M não encontrado</literal>.) Para converter rapidamente todos os arquivos de CR/LF para apenas LF, adicione essa entrada ao <filename>Makefile</filename> do port:</para> + + <programlisting>USES= dos2unix</programlisting> + + <para>Uma lista de arquivos específicos para conversão pode ser informada:</para> + + <programlisting>USES= dos2unix +DOS2UNIX_FILES= util.c util.h</programlisting> + + <para>Use <varname>DOS2UNIX_REGEX</varname> para converter um grupo de arquivos em subdiretórios. Seu argumento é um <citerefentry><refentrytitle>find</refentrytitle><manvolnum>1</manvolnum></citerefentry> compatível com expressão regular. Mais sobre o formato está em <citerefentry><refentrytitle>re_format</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Esta opção é útil para converter todos os arquivos de uma determinada extensão. Por exemplo, converta todos os arquivos de código-fonte, deixando os arquivos binários intactos:</para> + + <programlisting>USES= dos2unix +DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting> + + <para>Uma opção similar é <varname>DOS2UNIX_GLOB</varname>, que executa o <command>find</command> para cada elemento listado nele.</para> + + <programlisting>USES= dos2unix +DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting> + + + <para>O diretório base para a conversão pode ser definido. Isso é útil quando há vários distfiles e vários arquivos contidos que requerem conversão de fim de linha.</para> + + <programlisting>USES= dos2unix +DOS2UNIX_WRKSRC= ${WRKDIR}</programlisting> + </sect2> + + <sect2 xml:id="slow-patch-extra"> + <title>Corrigindo Condicionalmente</title> + + <para>Alguns ports precisam de patches que são aplicados apenas para versões específicas do FreeBSD ou quando uma determinada opção é ativada ou desativada. Os patches condicionais são especificados colocando-se os caminhos completos para os arquivos de patch em<varname>EXTRA_PATCHES</varname>.</para> + + <example xml:id="slow-patch-extra-ex1"> + <title>Aplicando um Patch para uma Versão Específica do FreeBSD</title> + + <programlisting>.include <bsd.port.options.mk> + +# Patch in the iconv const qualifier before this +.if ${OPSYS} == FreeBSD && ${OSVERSION} < 1100069 +EXTRA_PATCHES= ${PATCHDIR}/extra-patch-fbsd10 +.endif + +.include <bsd.port.mk></programlisting> + </example> + + <example xml:id="slow-patch-extra-ex2"> + <title>Aplicando Opcionalmente um Patch</title> + + <para>Quando um <link linkend="makefile-options">option</link> requer um patch, use<varname><replaceable>opt</replaceable>_EXTRA_PATCHES</varname> e <varname><replaceable>opt</replaceable>_EXTRA_PATCHES_OFF</varname> para fazer o patch condicional na opção <literal><replaceable>opt</replaceable></literal>. Veja <xref linkend="options-variables"/> Para maiores informações.</para> + + <programlisting>OPTIONS_DEFINE= FOO BAR +FOO_EXTRA_PATCHES= ${PATCHDIR}/extra-patch-foo +BAR_EXTRA_PATCHES_OFF= ${PATCHDIR}/extra-patch-bar.c \ + ${PATCHDIR}/extra-patch-bar.h</programlisting> + </example> + + <example xml:id="slow-patch-extra-ex-dirs"> + <title>Usando <varname>EXTRA_PATCHES</varname> Com um Diretório</title> + + <para>As vezes, existem muitos patches que são necessários para um recurso, neste caso, é possível apontar <varname>EXTRA_PATCHES</varname> para um diretório, e ele aplicará automaticamente todos os arquivos nomeados como <filename>patch<replaceable>*</replaceable></filename> nele.</para> + + <para>Crie um subdiretório em <filename>${PATCHDIR}</filename>, e mova os patches para ele. Por exemplo:</para> + + <screen><prompt>%</prompt> <userinput>ls -l <replaceable>files/foo-patches</replaceable></userinput> +-rw-r--r-- 1 root wheel 350 Jan 16 01:27 patch-Makefile.in +-rw-r--r-- 1 root wheel 3084 Jan 18 15:37 patch-configure</screen> + + <para>Então adicione isso ao <filename>Makefile</filename>:</para> + + <programlisting>OPTIONS_DEFINE= FOO +FOO_EXTRA_PATCHES= ${PATCHDIR}/foo-patches</programlisting> + + <para>O framework irá então usar todos os arquivos nomeados <filename>patch<replaceable>*</replaceable></filename> nesse diretório.</para> + </example> + </sect2> + </sect1> + + <sect1 xml:id="slow-configure"> + <title>Configurando</title> + + <para>Inclua quaisquer comandos de personalização adicionais no script <filename>configure</filename> e salve-o no subdiretório <filename>scripts</filename>. Como mencionado acima, também é possível fazer isso com targets no <filename>Makefile</filename> e/ou scripts com o nome <filename>pre-configure</filename> ou <filename>post-configure</filename>.</para> + </sect1> + + <sect1 xml:id="slow-user-input"> + <title>Manipulando a Entrada do Usuário</title> + + <para>Se o port requer intervenção do usuário para build, configure ou install, defina <varname>IS_INTERACTIVE</varname> no <filename>Makefile</filename>. Isso fará com que os <quote>overnight builds</quote> pulem ele. Se o usuário definir a variável <envar>BATCH</envar> em seu ambiente (e se o usuário definir a variável <envar>INTERATIVE</envar>, então <emphasis>apenas</emphasis> aqueles ports que requerem interação serão compilados). Isso economizará muito tempo perdido no conjunto de máquinas que continuamente compilam ports (veja abaixo).</para> + + <para>Também é recomendado que, se houver respostas padrão razoáveis para as perguntas, <varname>PACKAGE_BUILDING</varname> pode usado para desativar a intervenção do usuário quando o mesmo estiver definido. Isso nos permitirá compilar os pacotes para CDROMs e FTP.</para> + </sect1> +</chapter> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="makefiles"> + + <title>Configurando o Makefile</title> + + <para>Configurar o <filename>Makefile</filename> é bastante simples e, novamente, sugerimos examinar os exemplos existentes antes de começar. Além disso, há um <link linkend="porting-samplem">Makefile de exemplo</link> neste manual, então dê uma olhada e por favor siga a ordem das variáveis e seções naquele modelo para tornar o port mais fácil para os outros lerem.</para> + + <para>Considere estes problemas em sequência durante o projeto do novo <filename>Makefile</filename>:</para> + + <sect1 xml:id="makefile-source"> + <title>O Código Fonte Original</title> + + <para>Ele está em <varname>DISTDIR</varname> como um tarball <command>gzip</command> e é chamado de algo como <filename>foozolix-1.2.tar.gz</filename>? Se assim for, vá para o próximo passo. Caso contrário, o formato do arquivo de distribuição pode necessitar da substituição de uma ou mais das variáveis <varname>DISTVERSION</varname>, <varname>DISTNAME</varname>, <varname>EXTRACT_CMD</varname>, <varname>EXTRACT_BEFORE_ARGS</varname>, <varname>EXTRACT_AFTER_ARGS</varname>, <varname>EXTRACT_SUFX</varname> ou <varname>DISTFILES</varname>.</para> + + <para>Na pior das hipóteses, crie um target personalizado <buildtarget>do-extract</buildtarget> para substituir o padrão. Isso raramente é necessário.</para> + </sect1> + + <sect1 xml:id="makefile-naming"> + <title>Nomeando</title> + + <para>A primeira parte do <filename>Makefile</filename> do port o nomeia, descreve seu número de versão e o lista na categoria correta.</para> + + <sect2 xml:id="makefile-portname"> + <title><varname>PORTNAME</varname></title> + + <para>Setar <varname>PORTNAME</varname> ao nome base do software. Isso é usado como base para o pacote do FreeBSD, e para o <link linkend="makefile-distname"><varname>DISTNAME</varname></link>.</para> + + <important> + <para>O nome do pacote deve ser único em toda a árvore de ports. Certifique-se de que o <varname>PORTNAME</varname> já não está em uso por um port existente, e que nenhum outro port já tem o mesmo <varname>PKGBASE</varname>. Se o nome já tiver sido usado, adicione <link linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname> ou <varname>PKGNAMESUFFIX</varname></link>.</para> + </important> + </sect2> + + <sect2 xml:id="makefile-versions"> + <title>Versões, <varname>DISTVERSION</varname><emphasis> ou </emphasis><varname>PORTVERSION</varname></title> + + <para>Setar <varname>DISTVERSION</varname> para o número da versão do software.</para> + + <para><varname>PORTVERSION</varname> é a versão usada para o pacote do FreeBSD. Será automaticamente derivado de <varname>DISTVERSION</varname> para ser compatível com o esquema de versionamento de pacotes do FreeBSD. Se a versão contiver <emphasis>letras</emphasis>, pode ser necessário definir <varname>PORTVERSION</varname>e não <varname>DISTVERSION</varname>.</para> + + <important> + <para>Não é possível utilizar <varname>PORTVERSION</varname> e <varname>DISTVERSION</varname> juntos, deve ser ser definido um de cada vez.</para> + </important> + + <para>De tempos em tempos, alguns softwares usam um esquema de versão que não é compatível em como o <varname>DISTVERSION</varname> traduz a versão no <varname>PORTVERSION</varname>.</para> + + <tip> + <para>Ao atualizar um port, é possível usar o <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry> <option>-t</option> para verificar se a nova versão é maior ou menor do que antes. Veja <xref linkend="makefile-versions-ex-pkg-version"/>.</para> + </tip> + + <example xml:id="makefile-versions-ex-pkg-version"> + <title>Usando <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry> para comparar versões.</title> + + <para><command>pkg version -t</command> recebe duas versões como argumentos, responderá com <literal><</literal>, <literal>=</literal> ou <literal>></literal> se a primeira versão for menor, igual ou maior que a segunda versão, respectivamente.</para> + + <screen><prompt>%</prompt> <userinput>pkg version -t 1.2 1.3</userinput> +< <co xml:id="makefile-versions-tip-co1"/> +<prompt>%</prompt> <userinput>pkg version -t 1.2 1.2</userinput> += <co xml:id="makefile-versions-tip-co2"/> +<prompt>%</prompt> <userinput>pkg version -t 1.2 1.2.0</userinput> += <co xml:id="makefile-versions-tip-co3"/> +<prompt>%</prompt> <userinput>pkg version -t 1.2 1.2.p1</userinput> +> <co xml:id="makefile-versions-tip-co4"/> +<prompt>%</prompt> <userinput>pkg version -t 1.2.a1 1.2.b1</userinput> +< <co xml:id="makefile-versions-tip-co5"/> +<prompt>%</prompt> <userinput>pkg version -t 1.2 1.2p1</userinput> +< <co xml:id="makefile-versions-tip-co6"/></screen> + + <calloutlist> + <callout arearefs="makefile-versions-tip-co1"> + <para><literal>1.2</literal> é menor que <literal>1.3</literal>.</para> + </callout> + + <callout arearefs="makefile-versions-tip-co3"> + <para><literal>1.2</literal> e <literal>1.2</literal> são iguais, pois têm a mesma versão. </para> + </callout> + + <callout arearefs="makefile-versions-tip-co3"> + <para><literal>1.2</literal> e <literal>1.2.0</literal> são iguais, pois valor vazio é igual a zero.</para> + </callout> + + <callout arearefs="makefile-versions-tip-co4"> + <para><literal>1.2</literal> é maior que <literal>1.2.p1</literal> por causa do <literal>.p1</literal>, pense em <quote>pre-release 1</quote>.</para> + </callout> + + <callout arearefs="makefile-versions-tip-co4"> + <para><literal>1.2.a1</literal> é menor que <literal>1.2.b1</literal>, pense em <quote>alfa</quote> e <quote>beta</quote> e <literal>a</literal> é menor que <literal>b</literal>.</para> + </callout> + + <callout arearefs="makefile-versions-tip-co6"> + <para><literal>1.2</literal> é menor que <literal>1.2p1</literal> por causa do <literal>2p1</literal>, pense em <quote>2, nível de patch 1</quote> que é uma versão depois de qualquer <literal>2.X</literal> mas antes de <literal>3</literal>.</para> + </callout> + </calloutlist> + + <note> + <para>Aqui, <literal>a</literal>, <literal>b</literal> e <literal>p</literal> são usados como se significassem <quote>alfa</quote>, <quote>beta</quote> ou <quote>pre-release</quote> e <quote>nível de patch</quote>, mas elas são apenas letras e são classificados por ordem alfabética, portanto, qualquer letra pode ser utilizada, e elas serão ordenadas de forma adequada.</para> + </note> + </example> + + <table frame="none" pgwide="0"> + <title>Exemplos de <varname>DISTVERSION</varname> e de Derivações <varname>PORTVERSION</varname>.</title> + + <tgroup cols="2"> + <thead> + <row> + <entry><varname>DISTVERSION</varname></entry> + <entry><varname>PORTVERSION</varname></entry> + </row> + </thead> + + <tbody> + <row> + <entry>0.7.1d</entry> + <entry>0.7.1.d</entry> + </row> + + <row> + <entry>10Alpha3</entry> + <entry>10.a3</entry> + </row> + + <row> + <entry>3Beta7-pre2</entry> + <entry>3.b7.p2</entry> + </row> + + <row> + <entry>8:f_17</entry> + <entry>8f.17</entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="makefile-versions-ex1"> + <title>Usando <varname>DISTVERSION</varname></title> + + <para>Quando a versão contém apenas números separados por pontos, traços ou sublinhados, use <varname>DISTVERSION</varname>.</para> + + <programlisting>PORTNAME= nekoto +DISTVERSION= 1.2-4</programlisting> + + <para>Isso irá gerar um <varname>PORTVERSION</varname> <literal>1.2.4</literal>.</para> + </example> + + <example xml:id="makefile-versions-ex2"> + <title>Usando <varname>DISTVERSION</varname> Quando a Versão Começa com uma Letra ou um Prefixo</title> + + <para>Quando a versão começa ou termina com uma letra, um prefixo ou um sufixo que não faz parte da versão, use <varname>DISTVERSIONPREFIX</varname>, <varname>DISTVERSION</varname> e <varname>DISTVERSIONSUFFIX</varname>.</para> + + <para>Se a versão for <literal>v1.2-4</literal>:</para> + + <programlisting>PORTNAME= nekoto +DISTVERSIONPREFIX= v +DISTVERSION= 1_2_4</programlisting> + + <para>Algumas vezes, projetos usando <application>GitHub</application> usará seu nome em suas versões. Por exemplo, a versão pode ser <literal>nekoto-1.2-4</literal>:</para> + + <programlisting>PORTNAME= nekoto +DISTVERSIONPREFIX= nekoto- +DISTVERSION= 1.2_4</programlisting> + + <para>Esses projetos também usam algumas strings no final da versão, por exemplo,<literal>1.2-4_RELEASE</literal>:</para> + + <programlisting>PORTNAME= nekoto +DISTVERSION= 1.2-4 +DISTVERSIONSUFFIX= _RELEASE</programlisting> + + <para>Ou eles fazem ambos, por exemplo,<literal>nekoto-1.2-4_RELEASE</literal>:</para> + + <programlisting>PORTNAME= nekoto +DISTVERSIONPREFIX= nekoto- +DISTVERSION= 1.2-4 +DISTVERSIONSUFFIX= _RELEASE</programlisting> + + <para><varname>DISTVERSIONPREFIX</varname> e <varname>DISTVERSIONSUFFIX</varname> não serão usados durante a construção do <varname>PORTVERSION</varname>, mas usado apenas em <varname>DISTNAME</varname>.</para> + + <para>Todos exemplos irão gerar um <varname>PORTVERSION</varname> com valor <literal>1.2.4</literal>.</para> + </example> + + <example xml:id="makefile-versions-ex3"> + <title>Usando <varname>DISTVERSION</varname> Quando a Versão Contém Letras Significando <quote>alpha</quote>, <quote>beta</quote> ou <quote>pre-release</quote></title> + + <para>Quando a versão contém números separados por pontos, traços ou underlines, e letras são usadas para significar <quote>alpha</quote>, <quote>beta</quote> ou <quote>pre-release</quote>, no sentido de que vem antes das versões sem letras, use <varname>DISTVERSION</varname>.</para> + + <programlisting>PORTNAME= nekoto +DISTVERSION= 1.2-pre4</programlisting> + + <programlisting>PORTNAME= nekoto +DISTVERSION= 1.2p4</programlisting> + + <para>Ambos irão gerar um <varname>PORTVERSION</varname> com valor <literal>1.2.p4</literal> que é menor do que 1.2. <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry> pode ser usado para verificar esse fato:</para> + + <screen><prompt>%</prompt> <userinput>pkg version -t 1.2.p4 1.2</userinput> +<</screen> + </example> + + <example xml:id="makefile-versions-ex4"> + <title>Não use <varname>DISTVERSION</varname> Quando a Versão Contém Letras que Significam "Nível de Patch"</title> + + <para>Quando a versão contém letras que não significam <quote>alpha</quote>, <quote>beta</quote> ou <quote>pre</quote>, e estão mais para um <quote>nível de patch</quote>, no sentido de que vem depois da versão sem as letras, use <varname>PORTVERSION</varname>.</para> + + <programlisting>PORTNAME= nekoto +PORTVERSION= 1.2p4</programlisting> + + <para>Neste caso, usar <varname>DISTVERSION</varname> não é possível porque geraria uma versão <literal>1.2.p4</literal> o que seria menor que <literal>1.2</literal> e não maior.<citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry> irá constatar isso:</para> + + <screen><prompt>%</prompt> <userinput>pkg version -t 1.2 1.2.p4</userinput> +> <co xml:id="makefile-versions-ex4-co1"/> +<prompt>%</prompt> <userinput>pkg version -t 1.2 1.2p4</userinput> +< <co xml:id="makefile-versions-ex4-co2"/></screen> + + <calloutlist> + <callout arearefs="makefile-versions-ex4-co1"> + <para><literal>1.2</literal> é maior que <literal>1.2.p4</literal>, o que é <emphasis>errado</emphasis> nesse caso.</para> + </callout> + + <callout arearefs="makefile-versions-ex4-co2"> + <para><literal>1.2</literal> é menor que <literal>1.2p4</literal>, que é o que era necessário.</para> + </callout> + </calloutlist> + </example> + + <para>Para alguns exemplos mais avançados de configuração do <varname>PORTVERSION</varname>, quando a versão do software não é realmente compatível com o FreeBSD, ou <varname>DISTNAME</varname> quando o arquivo de distribuição não contém a versão em si, consulte <xref linkend="makefile-distname"/>.</para> + </sect2> + + <sect2 xml:id="makefile-naming-revepoch"> + <title><varname>PORTREVISION</varname> e <varname>PORTEPOCH</varname></title> + + <sect3 xml:id="makefile-portrevision"> + <title><varname>PORTREVISION</varname></title> + + <para><varname>PORTREVISION</varname> é um valor monotonicamente crescente que é redefinido para 0 com cada incremento de <varname>DISTVERSION</varname>, normalmente toda vez que houver uma nova versão oficial do fornecedor. E se <varname>PORTREVISION</varname> é diferente de zero, o valor é anexado ao nome do pacote. Mudanças em <varname>PORTREVISION</varname> são usadas por ferramentas automatizadas como <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry> para determinar se um novo pacote está disponível.</para> + + <para><varname>PORTREVISION</varname> deve ser incrementado toda vez que uma alteração for feita no port onde se altera o pacote gerado de alguma forma. Isso inclui alterações que afetam apenas um pacote compilado com <link linkend="makefile-options">options</link> não padrão.</para> + + <para>Exemplos de quando <varname>PORTREVISION</varname> deve ser alterado:</para> + + <itemizedlist> + <listitem> + <para>Adição de correções para corrigir vulnerabilidades de segurança, bugs ou para adicionar novas funcionalidades ao port.</para> + </listitem> + + <listitem> + <para>Alterações no <filename>Makefile</filename> do port para ativar ou desativar as opções de tempo de compilação no pacote.</para> + </listitem> + + <listitem> + <para>Alterações na lista de empacotamento ou no comportamento de tempo de instalação do pacote. Por exemplo, uma alteração em um script que gera dados iniciais para o pacote, como chaves de host <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + + <listitem> + <para>Bump de versão da dependência de biblioteca compartilhada de um port (nesse caso, alguém tentando instalar o pacote antigo depois de instalar uma versão mais nova da dependência falhará, pois procurará a libfoo.x antiga em vez da libfoo.(x+1)).</para> + </listitem> + + <listitem> + <para>Mudanças silenciosas no distfile do port que possuem diferenças funcionais significativas. Por exemplo, mudanças no distfile que requerem uma correção para <filename>distinfo</filename> sem alteração correspondente para <varname>DISTVERSION</varname>, onde um<command>diff -ru</command> das versões antiga e nova mostra mudanças não triviais no código.</para> + </listitem> + </itemizedlist> + + <para>Exemplos de alterações que não requerem uma alteração no <varname>PORTREVISION</varname>:</para> + + <itemizedlist> + <listitem> + <para>Mudanças de estilo no esqueleto do port sem alteração funcional ao que aparece no pacote resultante.</para> + </listitem> + + <listitem> + <para>Mudanças para <varname>MASTER_SITES</varname> ou outras alterações funcionais no port que não afetem o pacote resultante.</para> + </listitem> + + <listitem> + <para>Patches triviais para o distfile, como correção de erros de digitação, que não são importantes o suficiente para que os usuários do pacote tenham que se dar ao trabalho de atualizar.</para> + </listitem> + *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201810212353.w9LNriEW062019>