diff options
Diffstat (limited to 'pt_BR.ISO8859-1')
| -rw-r--r-- | pt_BR.ISO8859-1/books/Makefile | 1 | ||||
| -rw-r--r-- | pt_BR.ISO8859-1/books/porters-handbook/Makefile | 50 | ||||
| -rw-r--r-- | pt_BR.ISO8859-1/books/porters-handbook/book.xml | 23177 | ||||
| -rw-r--r-- | pt_BR.ISO8859-1/books/porters-handbook/pt_BR.po | 62366 |
4 files changed, 85594 insertions, 0 deletions
diff --git a/pt_BR.ISO8859-1/books/Makefile b/pt_BR.ISO8859-1/books/Makefile index 330e7233d1..ff49856435 100644 --- a/pt_BR.ISO8859-1/books/Makefile +++ b/pt_BR.ISO8859-1/books/Makefile @@ -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" diff --git a/pt_BR.ISO8859-1/books/porters-handbook/Makefile b/pt_BR.ISO8859-1/books/porters-handbook/Makefile new file mode 100644 index 0000000000..d70d4629c1 --- /dev/null +++ b/pt_BR.ISO8859-1/books/porters-handbook/Makefile @@ -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" diff --git a/pt_BR.ISO8859-1/books/porters-handbook/book.xml b/pt_BR.ISO8859-1/books/porters-handbook/book.xml new file mode 100644 index 0000000000..0b956ff631 --- /dev/null +++ b/pt_BR.ISO8859-1/books/porters-handbook/book.xml @@ -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> + + <listitem> + <para>Correções de compilação que fazem com que um pacote se torne compilável onde antes estava falhando. Desde que as alterações não introduzam nenhuma mudança funcional em nenhuma outra plataforma na qual o port tenha sido compilado anteriormente. <varname>PORTREVISION</varname> reflete o conteúdo do pacote, se o pacote não foi compilado anteriormente, então não há necessidade de incrementar o <varname>PORTREVISION</varname> para registrar uma mudança.</para> + </listitem> + </itemizedlist> + + <para>Uma regra geral é decidir se a mudança em um port é algo que <emphasis>algumas</emphasis> pessoas se beneficiariam em ter. Por causa de um aprimoramento, conserto ou em virtude de que o novo pacote funcione de fato. Em seguida, pondere que, de fato, isso fará com que todos que regularmente atualizam sua árvore de ports sejam obrigados a atualiza-lo. Se sim, <varname>PORTREVISION</varname> deve ser incrementado.</para> + + <note> + <para>Pessoas usando pacotes binários <emphasis>nunca</emphasis> verão a atualização se <varname>PORTREVISION</varname> não for incrementado. Sem incrementar <varname>PORTREVISION</varname>, os package builders não têm como detectar a alteração e, portanto, não irão recompilar o pacote.</para> + </note> + </sect3> + + <sect3 xml:id="makefile-portepoch"> + <title><varname>PORTEPOCH</varname></title> + + <para>De tempos em tempos, um fornecedor de software ou um mantenedor de port do FreeBSD fazem algo tolo e lançam uma versão de seu software que é numericamente menor que a versão anterior. Um exemplo disso é um port que vai de foo-20000801 para foo-1.0 ( o primeiro será incorretamente tratado como uma versão mais nova, já que 20000801 é um valor numericamente maior que 1).</para> + + <tip> + <para>Os resultados das comparações de números de versão nem sempre são óbvios. <command>pkg version</command> (veja <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry>) pode ser usado para testar a comparação de duas sequências de números de versão. Por exemplo:</para> + + <screen><prompt>%</prompt> <userinput>pkg version -t 0.031 0.29</userinput> +></screen> + + <para>A saida <literal>></literal> indica que a versão 0.031 é considerada maior que a versão 0.29, o que pode não ter sido óbvio para o mantenedor do port.</para> + </tip> + + <para>Em situações como essa, <varname>PORTEPOCH</varname> deve ser incrementado. E se <varname>PORTEPOCH</varname> é diferente de zero, ele é anexado ao nome do pacote conforme descrito na seção 0 acima. <varname>PORTEPOCH</varname> nunca deve ser diminuído ou redefinido para zero, porque isso faria com que a comparação com um pacote de uma época anterior falhasse. Por exemplo, o pacote não seria detectado como desatualizado. O novo número da versão, <literal>1.0.1</literal> no exemplo acima, ainda é numericamente menor que a versão anterior, 20000801, mas o sufixo <literal>1</literal> é tratado especialmente por ferramentas automatizadas e considerado maior que o sufixo <literal>0</literal> implícito no pacote anterior.</para> + + <para>Remover ou resetar o <varname>PORTEPOCH</varname> incorretamente conduz ao luto eterno. Se a discussão acima não foi clara o suficiente, por favor consulte a <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports"> Lista de discussão de ports do FreeBSD</link></para> + + <para>É esperado que <varname>PORTEPOCH</varname> não seja utilizado na maioria dos ports, e que seja feito o uso sensato do <varname>DISTVERSION</varname>, ou que o <varname>PORTVERSION</varname> seja usado com cuidado também, isso muitas vezes pode evitar que uma versão futura do software altere a estrutura da versão. No entanto, é necessário que os porters do FreeBSD tenham cuidado quando uma versão do fornecedor é feita sem um número de versão oficial - como um código de release <quote>snapshot</quote>. A tentação é rotular a release com a data de lançamento, o que causará problemas como no exemplo acima, quando um novo release <quote>oficial</quote> é feito.</para> + + <para>Por exemplo, se um snapshot de release é feito na data <literal>20000917</literal> e a versão anterior do software era a versão <literal>1.2</literal>, não use <literal>20000917</literal> no <varname>DISTVERSION</varname>. A maneira correta é um <varname>DISTVERSION</varname> com valor <literal>1.2.20000917</literal>, ou similar, para que a próxima versão, digamos <literal>1.3</literal>, ainda seja um valor numericamente maior.</para> + </sect3> + + <sect3 xml:id="makefile-portrevision-example"> + <title>Exemplo de Uso <varname>PORTREVISION</varname> e <varname>PORTEPOCH</varname></title> + + <para>O port <literal>gtkmumble</literal>, versão<literal>0.10</literal> está comitado na coleção de ports:</para> + + <programlisting>PORTNAME= gtkmumble +DISTVERSION= 0.10</programlisting> + + <para><varname>PKGNAME</varname> torna-se <literal>gtkmumble-0.10</literal>.</para> + + <para>Uma falha de segurança é descoberta, o que requer um patch local do FreeBSD. <varname>PORTREVISION</varname> é alterado de acordo.</para> + + <programlisting>PORTNAME= gtkmumble +DISTVERSION= 0.10 +PORTREVISION= 1</programlisting> + + <para><varname>PKGNAME</varname> torna-se <literal>gtkmumble-0.10_1</literal></para> + + <para>Uma nova versão é lançada pelo fornecedor, numerada como <literal>0.2</literal> (acontece que o autor realmente pretendia que <literal>0.10</literal> significa-se realmente <literal>0.1.0</literal>, não <quote>o que vem depois de 0.9</quote> - oops, tarde demais agora). Como a nova versão secundária <literal>2</literal> é numericamente menor que a versão anterior <literal>10</literal>, <varname>PORTEPOCH</varname> deve ser incrementado para forçar manualmente que o novo pacote seja detectado como <quote>mais recente</quote>. Como é uma nova versão do fornecedor, <varname>PORTREVISION</varname> é redefinido para 0 (ou removido do<filename>Makefile</filename>).</para> + + <programlisting>PORTNAME= gtkmumble +DISTVERSION= 0.2 +PORTEPOCH= 1</programlisting> + + <para><varname>PKGNAME</varname> torna-se <literal>gtkmumble-0.2,1</literal></para> + + <para>O próximo lançamento é 0.3. Desde que <varname>PORTEPOCH</varname> nunca diminua, as variáveis de versão são agora:</para> + + <programlisting>PORTNAME= gtkmumble +DISTVERSION= 0.3 +PORTEPOCH= 1</programlisting> + + <para><varname>PKGNAME</varname> torna-se <literal>gtkmumble-0.3,1</literal></para> + + <note> + <para>E se <varname>PORTEPOCH</varname> for redefinido para <literal>0</literal> com esta atualização, alguém que instalou o <literal>gtkmumble-0.10_1</literal> não detectaria o <literal>gtkmumble-0.3 </literal> como pacote mais novo, desde que <literal>3</literal> ainda é numericamente menor que <literal>10</literal>. Lembre-se, este é o ponto principal de <varname>PORTEPOCH</varname> em primeiro lugar.</para> + </note> + </sect3> + </sect2> + + <sect2 xml:id="porting-pkgnameprefix-suffix"> + <title><varname>PKGNAMEPREFIX</varname> e <varname>PKGNAMESUFFIX</varname></title> + + <para>Duas variáveis opcionais, <varname>PKGNAMEPREFIX</varname> e <varname>PKGNAMESUFFIX</varname>, são combinadas com <varname>PORTNAME</varname> e <varname>PORTVERSION</varname> para formar <varname>PKGNAME</varname> como <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. Certifique-se de que isto está de acordo com as nossas <link linkend="porting-pkgname">diretrizes para um bom nome de pacote</link>. Em particular, o uso de um hífen (<literal>-</literal>) dentro de <varname>PORTVERSION</varname> <emphasis>não é</emphasis> permitido. Além disso, se o nome do pacote tiver o <replaceable>language-</replaceable> ou a parte <replaceable>-compiled.specifics</replaceable> (veja abaixo), use <varname>PKGNAMEPREFIX</varname> e <varname>PKGNAMESUFFIX</varname>, respectivamente. Não os faça parte de <varname>PORTNAME</varname>.</para> + </sect2> + + <sect2 xml:id="porting-pkgname"> + <title>Convenções de Nomenclatura de Pacotes</title> + + <para>Estas são as convenções a serem seguidas ao nomear pacotes. Isso é para facilitar a varredura do diretório de pacotes, já que existem milhares de pacotes e os usuários irão pegar ranço se eles machucarem seus olhos!</para> + + <para>Nomes de pacotes tomam a forma de <filename><replaceable>language_region-name-compiled.specifics-version.numbers</replaceable></filename>.</para> + + <para>O nome do pacote é definido como <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. Certifique-se de definir as variáveis para estar em conformidade com esse formato.</para> + + <variablelist xml:id="porting-pkgname-format"> + <varlistentry xml:id="porting-pkgname-language"> + <term><filename><replaceable>language_region-</replaceable></filename></term> + + <listitem> + <para>O FreeBSD se esforça para suportar a linguagem nativa de seus usuários. A parte <replaceable>language-</replaceable> é uma abreviação de duas letras da linguagem natural definida pela ISO-639 quando o port é específico para um determinado idioma. Exemplos são <literal>ja</literal> para japonês, <literal>ru</literal> para russo,<literal>vi</literal> para vietnamita, <literal>zh</literal> para o chinês, <literal>ko</literal> para coreano e <literal>de</literal> para alemão.</para> + + <para>Se o port for específico de uma determinada região dentro da área de idioma, adicione também o código do país de duas letras. Exemplos são <literal>en_US</literal> para Inglês dos EUA e <literal>fr_CH</literal> para o Francês Suíço.</para> + + <para>A parte <replaceable>language-</replaceable> é definida em <varname>PKGNAMEPREFIX</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="porting-pkgname-name"> + <term><filename><replaceable>name</replaceable></filename></term> + + <listitem> + <para>Certifique-se de que o nome e a versão do port estejam claramente separados e colocados em <varname>PORTNAME</varname> e <varname>DISTVERSION</varname>. A única razão para <varname>PORTNAME</varname> conter uma parte da versão é se a distribuição upstream é realmente chamada dessa forma, como no <package role="port">textproc/libxml2</package> ou <package role="port">japanese/kinput2-freewnn</package>. De outra forma, <varname>PORTNAME</varname> não pode conter informações específicas da versão. É normal que vários ports tenham o mesmo <varname>PORTNAME</varname>, como os ports <package role="port">www/apache *</package> fazem; Nesse caso, versões diferentes (e entradas de índice diferentes) são distinguidas por valores <varname>PKGNAMEPREFIX</varname> e <varname>PKGNAMESUFFIX</varname>.</para> + + <para>Há uma tradição de nomear módulos <literal>Perl 5</literal> com sufixo <literal>p5-</literal> e convertendo o separador de dois pontos para um hífen. Por exemplo, o modulo <literal>Data::Dumper</literal> torna-se <literal>p5-Data-Dumper</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="porting-pkgname-compiled-specifics"> + <term><filename><replaceable>-compiled.specifics</replaceable></filename></term> + + <listitem> + <para>Se o port pode ser construído com diferentes <link linkend="makefile-masterdir">padrões codificados</link> (geralmente parte do nome do diretório em uma família de ports), a parte <replaceable>-compiled.specifics</replaceable> indica os padrões compilados. O hífen é opcional. Exemplos são tamanho de papel e unidades de fonte.</para> + + <para>A parte <replaceable>-compiled.specifics</replaceable> é definida em <varname>PKGNAMESUFFIX</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="porting-pkgname-version-numbers"> + <term><filename><replaceable>-version.numbers</replaceable></filename></term> + + <listitem> + <para>A string da versão segue um hífen (<literal>-</literal>) e é uma lista separada por pontos de números inteiros e letras minúsculas. Em particular, não é permitido ter outro hífen dentro da string de versão. A única exceção é a string <literal>pl</literal> (significando <quote>patchlevel</quote>), que pode ser usado <emphasis>apenas</emphasis> quando não há números de versão maiores e menores no software. Se a versão do software tiver sequências como <quote>alpha</quote>, <quote>beta</quote>, <quote>rc</quote> ou <quote>pre</quote>, use a primeira letra e coloque imediatamente após um ponto. Se a sequência da versão continuar após esses nomes, os números seguirão o alfabeto simples sem um ponto extra entre eles (por exemplo,<literal>1.0b2</literal>).</para> + + <para>A ideia é facilitar a classificação dos ports observando a string de versão. Em particular, certifique-se de que os componentes do número da versão estejam sempre delimitados por um ponto e, se a data fizer parte da string, use o formato <literal>d<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>, não <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal> ou o não compatível com o formato Y2K <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>. É importante prefixar a versão com uma letra, aqui<literal>d</literal> (para data), no caso de uma versão com um número de versão real, que seria numericamente inferior a <literal><replaceable>yyyy</replaceable></literal>.</para> + </listitem> + </varlistentry> + </variablelist> + + <important> + <para>O nome do pacote deve ser único entre todos os ports, verifique se ainda não existe um port com o mesmo <varname>PORTNAME</varname> e se houver, adicione um dos <link linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname> ou <varname>PKGNAMESUFFIX</varname></link>.</para> + </important> + + <para>Aqui estão alguns exemplos (reais) de como converter o nome como chamado pelos autores do software para um nome de pacote adequado, para cada linha, apenas um dos <varname>DISTVERSION</varname> ou <varname>PORTVERSION</varname> está definido, dependendo de qual seria usado no <filename>Makefile</filename>:</para> + + <table frame="none" pgwide="1"> + <title>Exemplos de Nomes de Pacotes</title> + + <tgroup cols="7"> + <thead> + <row> + <entry>Nome da Distribuição</entry> + <entry><varname>PKGNAMEPREFIX</varname></entry> + <entry><varname>PORTNAME</varname></entry> + <entry><varname>PKGNAMESUFFIX</varname></entry> + <entry><varname>DISTVERSION</varname></entry> + <entry><varname>PORTVERSION</varname></entry> + <entry>Razão ou comentário</entry> + </row> + </thead> + + <tbody> + <row> + <entry>mule-2.2.2</entry> + <entry>(vazio)</entry> + <entry>mule</entry> + <entry>(vazio)</entry> + <entry>2.2.2</entry> + <entry/> + <entry>Nenhuma alteração é necessária</entry> + </row> + + <row> + <entry>mule-1.0.1</entry> + <entry>(vazio)</entry> + <entry>mule</entry> + <entry>1</entry> + <entry>1.0.1</entry> + <entry/> + <entry>Esta é a versão 1 do <application>mule</application> e a versão 2 já existe.</entry> + </row> + + <row> + <entry>EmiClock-1.0.2</entry> + <entry>(vazio)</entry> + <entry>emiclock</entry> + <entry>(vazio)</entry> + <entry>1.0.2</entry> + <entry/> + <entry>Sem nomes em maiúsculas para programas individuais</entry> + </row> + + <row> + <entry>rdist-1.3alpha</entry> + <entry>(vazio)</entry> + <entry>rdist</entry> + <entry>(vazio)</entry> + <entry>1.3alfa</entry> + <entry/> + <entry>Versão será <literal>1.3.a</literal></entry> + </row> + + <row> + <entry>es-0.9-beta1</entry> + <entry>(vazio)</entry> + <entry>es</entry> + <entry>(vazio)</entry> + <entry>0.9-beta1</entry> + <entry/> + <entry>Versão será <literal>0.9.b1</literal></entry> + </row> + + <row> + <entry>mailman-2.0rc3</entry> + <entry>(vazio)</entry> + <entry>mailman</entry> + <entry>(vazio)</entry> + <entry>2.0rc3</entry> + <entry/> + <entry>Versão será<varname>2.0.r3</varname></entry> + </row> + + <row> + <entry>v3.3beta021.src</entry> + <entry>(vazio)</entry> + <entry>tiff</entry> + <entry>(vazio)</entry> + <entry/> + <entry>3.3</entry> + <entry>O que diabos foi isso afinal?</entry> + </row> + + <row> + <entry>tvtwm</entry> + <entry>(vazio)</entry> + <entry>tvtwm</entry> + <entry>(vazio)</entry> + <entry/> + <entry>p11</entry> + <entry>Nenhuma versão no nome do arquivo, use o que o upstream diz que é</entry> + </row> + + <row> + <entry>piewm</entry> + <entry>(vazio)</entry> + <entry>piewm</entry> + <entry>(vazio)</entry> + <entry>1.0</entry> + <entry/> + <entry>Nenhuma versão no nome do arquivo, use o que o upstream diz que é</entry> + </row> + + <row> + <entry>xvgr-2.10pl1</entry> + <entry>(vazio)</entry> + <entry>xvgr</entry> + <entry>(vazio)</entry> + <entry/> + <entry>2.10.pl1</entry> + <entry>Nesse caso,<literal>pl1</literal> significa nível de patch, então usar DISTVERSION não é possível.</entry> + </row> + + <row> + <entry>gawk-2.15.6</entry> + <entry>ja-</entry> + <entry>gawk</entry> + <entry>(vazio)</entry> + <entry>2.15.6</entry> + <entry/> + <entry>Versão em japonês</entry> + </row> + + <row> + <entry>psutils-1.13</entry> + <entry>(vazio)</entry> + <entry>psutils</entry> + <entry>-letter</entry> + <entry>1.13</entry> + <entry/> + <entry>Tamanho do papel codificado no tempo de compilação do pacote</entry> + </row> + + <row> + <entry>pkfonts</entry> + <entry>(vazio)</entry> + <entry>pkfonts</entry> + <entry>300</entry> + <entry>1.0</entry> + <entry/> + <entry>Pacote para fontes de 300dpi</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Se não houver absolutamente nenhum rastro de informações de versão co código fonte original e é improvável que o autor original vá liberar outra versão, basta definir a string de versão para <literal>1.0</literal> (como o exemplo <literal>piewm</literal> acima). Caso contrário, pergunte ao autor original ou use a string de data com valor de quando a código fonte foi lançado como (<literal>d<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> ou <literal>d<replaceable>yyyy</replaceable><replaceable>mm</replaceable><replaceable>dd</replaceable></literal>) como a versão.</para> + + <tip> + <para>Use qualquer letra. Aqui,<literal>d</literal> significa data, se o código for um repositório do <application>Git</application>, <literal>g</literal> seguido pela data de commit é normalmente utilizado, <literal>s</literal> para snapshot também é comum.</para> + </tip> + </sect2> + </sect1> + + <sect1 xml:id="makefile-categories"> + <title>Categorização</title> + + <sect2 xml:id="makefile-categories-definition"> + <title><varname>CATEGORIES</varname></title> + + <para>Quando um pacote é criado, ele é colocado em <filename>/usr/ports/packages/All</filename> e links são feitos de um ou mais subdiretórios de <filename>/usr/ports/packages</filename>. Os nomes desses subdiretórios são especificados pela variável <varname>CATEGORIES</varname>. O objetivo é facilitar a vida do usuário quando ele estiver vasculhando a pilha de pacotes no site FTP ou no CD-ROM. Por favor, dê uma olhada na <link linkend="porting-categories">lista atual de categorias</link> e escolha as que são adequadas para o port.</para> + + <para>Esta lista também determina de onde, na árvore de ports, o port será importado. Se houver mais de uma categoria aqui, os arquivos do port devem ser colocados no subdiretório com o nome da primeira categoria. Veja <link linkend="choosing-categories">abaixo</link> para mais informação sobre como escolher as categorias certas.</para> + </sect2> + + <sect2 xml:id="porting-categories"> + <title>Lista Atual de Categorias</title> + + <para>Aqui está a lista atual de categorias de ports. As marcadas com um asterisco (<literal>*</literal>) são categorias <emphasis>virtuais</emphasis> - aquelas que não possuem um subdiretório correspondente na árvore de ports. Elas são usadas apenas como categorias secundárias e apenas para fins de pesquisa.</para> + + <note> + <para>Para categorias não virtuais, há uma descrição de uma linha em <varname>COMMENT</varname> no <filename>Makefile</filename> desse subdiretório.</para> + </note> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Categoria</entry> + <entry>Descrição</entry> + <entry>Notas</entry> + </row> + </thead> + + <tbody> + <row> + <entry><filename>accessibility</filename></entry> + <entry>Ports para ajudar usuários com deficiências.</entry> + <entry/> + </row> + + <row> + <entry><filename>afterstep</filename> <literal>*</literal></entry> + + <entry>Ports para apoiar o gerenciador de janelas <link xlink:href="http://www.afterstep.org">AfterStep</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>arabic</filename></entry> + <entry>Suporte ao idioma árabe"</entry> + <entry/> + </row> + + <row> + <entry><filename>archivers</filename></entry> + <entry>Ferramentas de arquivamento.</entry> + <entry/> + </row> + + <row> + <entry><filename>astro</filename></entry> + <entry>Ports astronômicos.</entry> + <entry/> + </row> + + <row> + <entry><filename>audio</filename></entry> + <entry>Suporte de som.</entry> + <entry/> + </row> + + <row> + <entry><filename>benchmarks</filename></entry> + <entry>Utilitários de benchmarking.</entry> + <entry/> + </row> + + <row> + <entry><filename>biology</filename></entry> + <entry>Software relacionado à biologia.</entry> + <entry/> + </row> + + <row> + <entry><filename>cad</filename></entry> + <entry>Ferramentas de desenho assistidas por computador.</entry> + <entry/> + </row> + + <row> + <entry><filename>chinese</filename></entry> + <entry>Suporte ao idioma chinês.</entry> + <entry/> + </row> + + <row> + <entry><filename>comms</filename></entry> + <entry>Software de comunicação.</entry> + <entry>Principalmente software para falar com o port serial.</entry> + </row> + + <row> + <entry><filename>converters</filename></entry> + <entry>Conversores de código de caracteres.</entry> + <entry/> + </row> + + <row> + <entry><filename>databases</filename></entry> + <entry>Bancos de dados.</entry> + <entry/> + </row> + + <row> + <entry><filename>deskutils</filename></entry> + <entry>Coisas que costumavam estar na área de trabalho antes dos computadores serem inventados.</entry> + <entry/> + </row> + + <row> + <entry><filename>devel</filename></entry> + <entry>Utilitários de desenvolvimento.</entry> + <entry>Não coloque bibliotecas aqui só porque são bibliotecas. Elas <emphasis>não deveriam</emphasis> estar nesta categoria, a menos que elas realmente não pertençam a nenhum outro lugar.</entry> + </row> + + <row> + <entry><filename>dns</filename></entry> + <entry>Software relacionado ao DNS.</entry> + <entry/> + </row> + + <row> + <entry><filename>docs</filename> <literal>*</literal></entry> + <entry>Meta-ports para documentação do FreeBSD.</entry> + <entry/> + </row> + + <row> + <entry><filename>editors</filename></entry> + <entry>Editores gerais.</entry> + <entry>Editores especializados entram na seção para essas ferramentas. Por exemplo, um editor de fórmula matemática <filename>math</filename>, e tem<filename> editores </filename>como uma segunda categoria.</entry> + </row> + + <row> + <entry><filename>elisp</filename> <literal>*</literal></entry> + <entry>Emacs-lisp ports.</entry> + <entry/> + </row> + + <row> + <entry><filename>emulators</filename></entry> + <entry>Emuladores para outros sistemas operacionais.</entry> + <entry>Emuladores de terminal <emphasis>não</emphasis> estão aqui. Os baseados em X vão para o <filename>x11</filename> e baseados em texto para qualquer <filename>comms</filename> ou <filename>misc</filename>, dependendo da funcionalidade exata.</entry> + </row> + + <row> + <entry><filename>finance</filename></entry> + <entry>Aplicações monetárias, financeiras e relacionadas.</entry> + <entry/> + </row> + + <row> + <entry><filename>french</filename></entry> + <entry>Suporte ao idioma francês.</entry> + <entry/> + </row> + + <row> + <entry><filename>ftp</filename></entry> + <entry>Utilitários de cliente e servidor de<acronym>FTP</acronym>.</entry> + <entry>Se o port fala com <acronym>FTP</acronym> e <acronym>HTTP</acronym>, coloque-o em <filename>ftp</filename> com uma categoria secundária de <filename>www</filename>.</entry> + </row> + + <row> + <entry><filename>games</filename></entry> + <entry>Jogos.</entry> + <entry/> + </row> + + <row> + <entry><filename>geography</filename> <literal>*</literal></entry> + <entry>Software relacionado à geografia.</entry> + <entry/> + </row> + + <row> + <entry><filename>german</filename></entry> + <entry>Suporte ao idioma alemão.</entry> + <entry/> + </row> + + <row> + <entry><filename>gnome</filename> <literal>*</literal></entry> + <entry>Ports do Projeto<link xlink:href="http://www.gnome.org">GNOME</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>gnustep</filename> <literal>*</literal></entry> + <entry>Software relacionado ao ambiente de desktop GNUstep.</entry> + <entry/> + </row> + + <row> + <entry><filename>graphics</filename></entry> + <entry>Utilitários gráficos.</entry> + <entry/> + </row> + + <row> + <entry><filename>hamradio</filename> <literal>*</literal></entry> + <entry>Software para rádio amador.</entry> + <entry/> + </row> + + <row> + <entry><filename>haskell</filename> <literal>*</literal></entry> + <entry>Software relacionado à linguagem Haskell.</entry> + <entry/> + </row> + + <row> + <entry><filename>hebrew</filename></entry> + <entry>Suporte ao idioma hebraico.</entry> + <entry/> + </row> + + <row> + <entry><filename>hungarian</filename></entry> + <entry>Suporte de idioma húngaro.</entry> + <entry/> + </row> + + <row> + <entry><filename>ipv6</filename> <literal>*</literal></entry> + <entry>Software relacionado ao IPv6</entry> + <entry/> + </row> + + <row> + <entry><filename>irc</filename></entry> + <entry>Utilitários do Internet Relay Chat.</entry> + <entry/> + </row> + + <row> + <entry><filename>japanese</filename></entry> + <entry>Suporte ao idioma japonês.</entry> + <entry/> + </row> + + <row> + <entry><filename>java</filename></entry> + <entry>Software relacionado à linguagem Java™.</entry> + <entry>A categoria <filename>Java</filename> não deve ser única para um port. Salvo para ports diretamente relacionadas à linguagem Java, os mantenedores de ports também são encorajados a não usar <filename>Java</filename> como a principal categoria de um port.</entry> + </row> + + <row> + <entry><filename>kde</filename> <literal>*</literal></entry> + <entry>Ports do Projeto<link xlink:href="http://www.kde.org">KDE</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>kld</filename> <literal>*</literal></entry> + <entry>Módulos carregáveis do kernel.</entry> + <entry/> + </row> + + <row> + <entry><filename>korean</filename></entry> + <entry>Suporte ao idioma coreano.</entry> + <entry/> + </row> + + <row> + <entry><filename>lang</filename></entry> + <entry>Linguagens de programação.</entry> + <entry/> + </row> + + <row> + <entry><filename>linux</filename> <literal>*</literal></entry> + <entry>Aplicações Linux e utilitários de suporte.</entry> + <entry/> + </row> + + <row> + <entry><filename>lisp</filename> <literal>*</literal></entry> + <entry>Software relacionado à linguagem Lisp.</entry> + <entry/> + </row> + + <row> + <entry><filename>mail</filename></entry> + <entry>Mail software.</entry> + <entry/> + </row> + + <row> + <entry><filename>math</filename></entry> + <entry>Software de computação numérica e outras utilidades para matemática.</entry> + <entry/> + </row> + + <row> + <entry><filename>mbone</filename> <literal>*</literal></entry> + <entry>Aplicações MBone.</entry> + <entry/> + </row> + + <row> + <entry><filename>misc</filename></entry> + <entry>Utilitários diversos</entry> + <entry>Coisas que não pertencem em nenhum outro lugar. Se possível, tente encontrar uma categoria melhor para o port do que <literal>misc</literal>, como os ports tendem a ser negligenciados aqui.</entry> + </row> + + <row> + <entry><filename>multimedia</filename></entry> + <entry>Software multimídia.</entry> + <entry/> + </row> + + <row> + <entry><filename>net</filename></entry> + <entry>Software de rede diversos.</entry> + <entry/> + </row> + + <row> + <entry><filename>net-im</filename></entry> + <entry>Software de mensagens instantâneas.</entry> + <entry/> + </row> + + <row> + <entry><filename>net-mgmt</filename></entry> + <entry>Software de gerenciamento de rede.</entry> + <entry/> + </row> + + <row> + <entry><filename>net-p2p</filename></entry> + <entry>Aplicativos de rede peer to peer.</entry> + <entry/> + </row> + + <row> + <entry><filename>news</filename></entry> + <entry>Software de notícias USENET.</entry> + <entry/> + </row> + + <row> + <entry><filename>palm</filename></entry> + + <entry>Suporte de software para a série <link xlink:href="http://www.palm.com/">Palm ™</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>parallel</filename> <literal>*</literal></entry> + <entry>Aplicativos que lidam com o paralelismo na computação.</entry> + <entry/> + </row> + + <row> + <entry><filename>pear</filename> <literal>*</literal></entry> + <entry>Ports relacionados ao framework PHP Pear.</entry> + <entry/> + </row> + + <row> + <entry><filename>perl5</filename> <literal>*</literal></entry> + <entry>Ports que exigem <application>Perl</application> versão 5 para rodar.</entry> + <entry/> + </row> + + <row> + <entry><filename>plan9</filename> <literal>*</literal></entry> + + <entry>Vários programas de <link xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>polish</filename></entry> + <entry>Suporte ao idioma polonês"</entry> + <entry/> + </row> + + <row> + <entry><filename>ports-mgmt</filename></entry> + <entry>Ports para gerenciar, instalar e desenvolver ports e pacotes do FreeBSD.</entry> + </row> + + <row> + <entry><filename>portuguese</filename></entry> + <entry>Suporte ao idioma Português.</entry> + <entry/> + </row> + + <row> + <entry><filename>print</filename></entry> + <entry>Software de Impressão.</entry> + <entry>As ferramentas de editoração eletrônica (pré-visualizadores etc.) também pertencem aqui.</entry> + </row> + + <row> + <entry><filename>python</filename> <literal>*</literal></entry> + + <entry>Software relacionado a linguagem<link xlink:href="http://www.python.org/">Python</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>ruby</filename> <literal>*</literal></entry> + <entry>Software relacionado a linguagem<link xlink:href="http://www.ruby-lang.org/">Ruby</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>rubygems</filename> <literal>*</literal></entry> + + <entry>Ports de pacotes <link xlink:href="http://www.rubygems.org/">RubyGems</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>russian</filename></entry> + <entry>Suporte de idioma russo.</entry> + <entry/> + </row> + + <row> + <entry><filename>scheme</filename> <literal>*</literal></entry> + <entry>Software relacionado à linguagem Scheme.</entry> + <entry/> + </row> + + <row> + <entry><filename>science</filename></entry> + <entry>Ports científicos que não se encaixam em outras categorias, como <filename>astro</filename>, <filename>biologia</filename> e <filename>matemática</filename></entry> + <entry/> + </row> + + <row> + <entry><filename>security</filename></entry> + <entry>Utilitários de segurança.</entry> + <entry/> + </row> + + <row> + <entry><filename>shells</filename></entry> + <entry>Linha de comando do shell.</entry> + <entry/> + </row> + + <row> + <entry><filename>spanish</filename> <literal>*</literal></entry> + <entry>Suporte ao idioma espanhol.</entry> + <entry/> + </row> + + <row> + <entry><filename>sysutils</filename></entry> + <entry>Utilidades do sistema.</entry> + <entry/> + </row> + + <row> + <entry><filename>tcl</filename> <literal>*</literal></entry> + <entry>Ports que usam o Tcl para rodar.</entry> + <entry/> + </row> + + <row> + <entry><filename>textproc</filename></entry> + <entry>Utilitários de processamento de texto.</entry> + <entry>Não inclui ferramentas de editoração eletrônica, que vão para <filename>print</filename></entry> + </row> + + <row> + <entry><filename>tk</filename> <literal>*</literal></entry> + <entry>Ports que usam o Tk para rodar.</entry> + <entry/> + </row> + + <row> + <entry><filename>ukrainian</filename></entry> + <entry>Suporte de idioma Ucraniano.</entry> + <entry/> + </row> + + <row> + <entry><filename>vietnamese</filename></entry> + <entry>Suporte de idioma Vietnamita.</entry> + <entry/> + </row> + + <row> + <entry><filename>windowmaker</filename> <literal>*</literal></entry> + <entry>Ports para suportar o gerenciador de janelas do WindowMaker.</entry> + <entry/> + </row> + + <row> + <entry><filename>www</filename></entry> + <entry>Software relacionado à World Wide Web.</entry> + <entry>O suporte ao idioma HTML também pertence aqui.</entry> + </row> + + <row> + <entry><filename>x11</filename></entry> + <entry>O X Window System e seus amigos.</entry> + <entry>Esta categoria é apenas para software que suporta diretamente o sistema de janelas. Não coloque aplicativos regulares do X aqui. A maioria deles é usada em outras categorias <filename>x11- *</filename> (veja abaixo).</entry> + </row> + + <row> + <entry><filename>x11-clocks</filename></entry> + <entry>X11 relógios.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-drivers</filename></entry> + <entry>Drivers X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-fm</filename></entry> + <entry>Gerentes de arquivos X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-fonts</filename></entry> + <entry>Fontes X11 e utilitários de fonte.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-servers</filename></entry> + <entry>Servidores X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-themes</filename></entry> + <entry>X11 temas.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-toolkits</filename></entry> + <entry>Kits de ferramentas X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-wm</filename></entry> + <entry>Gerentes de janela do X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>xfce</filename> <literal>*</literal></entry> + <entry>Ports relacionados com o ambiente de trabalho <link xlink:href="http://www.xfce.org/">Xfce</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>zope</filename> <literal>*</literal></entry> + <entry><link xlink:href="http://www.zope.org/">Zope</link> suporte.</entry> + <entry/> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2 xml:id="choosing-categories"> + <title>Escolhendo a Categoria Correta</title> + + <para>Como muitas das categorias se sobrepõem, escolher qual das categorias será a principal categoria do port pode ser entediante. Existem várias regras que governam essa questão. Aqui está a lista de prioridades, em ordem decrescente de precedência:</para> + + <itemizedlist> + <listitem> + <para>A primeira categoria deve ser uma categoria física (veja <link linkend="porting-categories">acima</link>). Isso é necessário para o empacotamento funcionar. Categorias virtuais e categorias físicas podem ser misturadas depois disso.</para> + </listitem> + + <listitem> + <para>As categorias específicas de idioma sempre vêm em primeiro lugar. Por exemplo, se o port instalar fontes X11 em japonês, a linha <varname>CATEGORIES</varname> deve ser <filename>japanese x11-fonts</filename>.</para> + </listitem> + + <listitem> + <para>Categorias específicas são listadas antes de outras menos específicas. Por exemplo, um editor de HTML é listado como <filename>www editors</filename>, e não ao contrário. Além disso, não insira <filename>net</filename> quando o port pertencer a qualquer uma das categorias <filename>irc</filename>, <filename>mail</filename>, <filename>news</filename>, <filename>security</filename> ou <filename>www</filename>, pois <filename>net</filename> está incluída implicitamente.</para> + </listitem> + + <listitem> + <para><filename>x11</filename> é usado como uma categoria secundária somente quando a categoria principal é uma linguagem natural. Em particular, não coloque <filename>x11</filename> na linha de categoria em aplicações X.</para> + </listitem> + + <listitem> + <para>Os modes <application>Emacs</application> são colocados na mesma categoria de ports que a aplicação suportada pelo mode, e não em <filename>editors</filename>. Por exemplo, um mode <application>Emacs</application> para editar código fonte de alguma linguagem de programação entra em <filename>lang</filename>.</para> + </listitem> + + <listitem> + <para>Ports que instalam módulos do kernel carregáveis também têm a categoria virtual <filename>kld</filename> na sua linha <varname>CATEGORIES</varname>. Esta é uma das coisas tratadas automaticamente adicionando <literal>USES=kmod</literal>.</para> + </listitem> + + <listitem> + <para><filename>misc</filename> não aparece com nenhuma outra categoria não virtual. Se houver <literal>misc</literal> com outra categoria na linha <varname>CATEGORIES</varname>, isso significa que <literal>misc</literal> pode ser seguramente excluído e o port colocado apenas no outro subdiretório.</para> + </listitem> + + <listitem> + <para>Se o port realmente não pertencer em nenhum outro lugar, coloque-o em <filename>misc</filename>.</para> + </listitem> + </itemizedlist> + + <para>Se a categoria não estiver claramente definida, por favor, insira um comentário sobre isso na submissão <link xlink:href="https://bugs.freebsd.org/submit/">do port</link> no banco de dados de bugs, para que possamos discuti-lo antes de importá-lo. Como committer, envie uma mensagem para a <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">lista de discussão de ports do FreeBSD</link>, para podermos discutir isso primeiro. Com muita frequência, novos ports são importados na categoria errada, e depois são movidos imediatamente para a categoria correta.</para> + </sect2> + + <sect2 xml:id="proposing-categories"> + <title>Propondo uma Nova Categoria</title> + + <para>Como a Coleção de Ports vem crescendo com o tempo, várias novas categorias também são adicionadas. Novas categorias podem ser categorias <emphasis>virtuais</emphasis>- aquelas que não possuem um subdiretório correspondente na árvore de ports - ou <emphasis>físicas</emphasis> - aquelas que possuem. Esta seção discute os problemas envolvidos na criação de uma nova categoria física. Leia atentamente antes de propor uma nova.</para> + + <para>Nossa prática atual tem sido a de evitar a criação de uma nova categoria física, a menos que um grande número de ports logicamente pertençam a ela, ou os ports que pertenceriam a ela sejam um grupo logicamente distinto de interesse geral limitado (por exemplo, categorias relacionadas com as línguas humanas faladas), ou de preferência ambas.</para> + + <para>A razão para isto é que tal mudança cria uma <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide/#ports">quantidade grande de trabalho</link> tanto para os committers quanto para todos os usuários que rastreiam alterações na coleção de ports. Além disso, propostas de alteração de categorias parecem naturalmente atrair controvérsias. (Talvez isso seja porque não há um consenso claro sobre quando uma categoria é <quote>grande o suficiente</quote>, nem quando as categorias devem ser apenas para propósitos de busca (e, portanto, qual número de categorias seria um número ideal), e assim por diante.).</para> + + <para>Aqui está o procedimento:</para> + + <procedure> + <step> + <para>Proponha a nova categoria na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">lista de discussão de ports do FreeBSD</link>. Inclua uma justificativa detalhada para a nova categoria, incluindo por que as categorias existentes não são suficientes, e a lista de ports existentes propostos para a mudança. (Se houver novos ports pendentes no <application>Bugzilla</application> que caberia nessa categoria, liste-os também.) Se você for o mantenedor e/ou o apresentador, respectivamente, mencione isso, pois isso pode ajudar no caso.</para> + </step> + + <step> + <para>Participe da discussão.</para> + </step> + + <step> + <para>Se parecer que há apoio o suficiente para a ideia, registre um PR que inclua a lógica e a lista de ports existentes que precisam ser movidos. O ideal é que este PR também inclua essas alterações:</para> + + <itemizedlist> + <listitem> + <para><filename>Makefile</filename>s para os novos ports, uma vez que sejam recopiados </para> + </listitem> + + <listitem> + <para><filename>Makefile</filename> para a nova categoria</para> + </listitem> + + <listitem> + <para><filename>Makefile</filename> para as categorias dos ports antigos</para> + </listitem> + + <listitem> + <para><filename>Makefile</filename>s para ports que dependem dos ports antigos </para> + </listitem> + + <listitem> + <para>(para crédito extra, inclua os outros arquivos que precisam ser alterados, conforme o procedimento no Guia do Committer.)</para> + </listitem> + </itemizedlist> + </step> + + <step> + <para>Como isso afeta a infraestrutura do ports e envolve a movimentação e alteração de vários ports, pode ser necessário executar testes de regressão no cluster de build, e portanto, atribua o PR para a Equipe de Gerenciamento de Ports <email>portmgr@FreeBSD.org</email>.</para> + </step> + + <step> + <para>Se esse PR for aprovado, um committer precisará seguir o restante do procedimento que é <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide/article.html#PORTS">descrito no Guia do Committer</link>.</para> + </step> + </procedure> + + <para>A proposta de uma nova categoria virtual é semelhante à acima, mas muito menos trabalhoso, já que nenhum port terá que ser movido. Nesse caso, os únicos patches a serem incluídos no PR serão aqueles para adicionar a nova categoria na linha <varname>CATEGORIES</varname> dos ports afetados.</para> + </sect2> + + <sect2 xml:id="proposing-reorg"> + <title>Propondo Reorganizar Todas as Categorias</title> + + <para>Ocasionalmente alguém propõe reorganizar as categorias com uma estrutura de dois níveis, ou algum outro tipo de estrutura de palavras-chave. Até o momento, nada vem de nenhuma dessas propostas porque, embora sejam muito fáceis de fazer, o esforço envolvido com qualquer readequação de toda a coleção de ports existente é assustadora, para se dizer o mínimo. Por favor, leia o histórico dessas propostas nos arquivos da lista de discussão antes de postar essa idéia. Além disso, esteja preparado para ser desafiado a oferecer um protótipo funcional.</para> + </sect2> + </sect1> + + <sect1 xml:id="makefile-distfiles"> + <title>Os Arquivos de Distribuição</title> + + <para>A segunda parte do <filename>Makefile</filename> descreve os arquivos que devem ser baixados para compilar o port e onde eles podem ser baixados.</para> + + <sect2 xml:id="makefile-distname"> + <title><varname>DISTNAME</varname></title> + + <para><varname>DISTNAME</varname> é o nome do port, conforme chamado pelos autores do software. <varname>DISTNAME</varname> é derivado de <literal>${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal>, e se não estiver definido, <varname>DISTVERSION</varname> é derivado de <literal>${PORTVERSION}</literal>, portanto altere <varname>DISTNAME</varname> somente se necessário. <varname>DISTNAME</varname> é usado apenas em dois lugares. Primeiro, na lista de arquivos de distribuição (<varname>DISTFILES</varname>) padrão para <literal>${DISTNAME}</literal><literal>${EXTRACT_SUFX}</literal>. Em segundo lugar, espera-se que o arquivo de distribuição seja extraído em um subdiretório denominado <varname>WRKSRC</varname>, cujo padrão é <filename>work/${DISTNAME}</filename>.</para> + + <para>Alguns nomes de distribuição de fornecedores que não se encaixam no <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme podem ser tratados automaticamente configurando <varname>DISTVERSIONPREFIX</varname>, <varname>DISTVERSION</varname> e <varname>DISTVERSIONSUFFIX</varname>. <varname>PORTVERSION</varname> será derivado de <varname>DISTVERSION</varname> automaticamente.</para> + + <important> + <para>Apenas um dos <varname>PORTVERSION</varname> e <varname>DISTVERSION</varname> pode ser definido de cada vez. E se <varname>DISTVERSION</varname> não derivar um <varname>PORTVERSION</varname> correto, não use <varname>DISTVERSION</varname>.</para> + </important> + + <para>Se o esquema de versão upstream puder ser derivado em um esquema de versão compatível com o ports, defina uma variável para a versão upstream, <emphasis>não</emphasis> use <varname>DISTVERSION</varname> como o nome da variável. Defina <varname>PORTVERSION</varname> para a versão computada com base na variável criada, e defina <varname>DISTNAME</varname> adequadamente.</para> + + <para>Se o esquema de versão upstream não puder ser facilmente configurado para um valor compatível com o ports, defina <varname>PORTVERSION</varname> para um valor sensato, e defina <varname>DISTNAME</varname> com <varname>PORTNAME</varname> com a versão literal do upstream.</para> + + <example xml:id="makefile-distname-ex1"> + <title>Derivando <varname>PORTVERSION</varname> Manualmente</title> + + <para><application>BIND9</application> usa um esquema de versão que não é compatível com as versões de ports (tem <literal>-</literal> em suas versões) e não pode ser derivado usando <varname>DISTVERSION</varname> porque após a versão 9.9.9, será lançado <quote>patchlevels</quote> na forma <literal>9.9.9-P1</literal>. DISTVERSION iria traduzir isso para <literal>9.9.9.p1</literal>, que no esquema de versionamento de ports significa 9.9.9 pré-release 1, que vem antes de 9.9.9 e não depois. Assim <varname>PORTVERSION</varname> é derivado manualmente de uma variável <varname>ISCVERSION</varname> para retornar <literal>9.9.9p1</literal>.</para> + + <para>A ordem na qual o framework do ports e o pkg ordenará as versões, é verificada usando o argumento <literal>-t</literal> do <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry>:</para> + + <screen><prompt>%</prompt> <userinput>pkg version -t 9.9.9 9.9.9.p1</userinput> +> <co xml:id="distversion-ex1-gt"/> +<prompt>%</prompt> <userinput>pkg version -t 9.9.9 9.9.9p1</userinput> +< <co xml:id="distversion-ex1-lt"/></screen> + + <calloutlist> + <callout arearefs="distversion-ex1-gt"> + <para>O sinal <literal>></literal> significa que o primeiro argumento passado em <literal>-t</literal> é maior que o segundo argumento. <literal>9.9.9</literal> é maior que <literal>9.9.9.p1</literal>.</para> + </callout> + + <callout arearefs="distversion-ex1-lt"> + <para>O sinal <literal><</literal> significa que o primeiro argumento passado em <literal>-t</literal> é menor que o segundo argumento. <literal>9.9.9</literal> é menor que <literal>9.9.9p1</literal>.</para> + </callout> + </calloutlist> + + <para>No <filename>Makefile</filename> do port, por exemplo <package role="port">dns/bind99</package>, é alcançado por:</para> + + <programlisting>PORTNAME= bind +PORTVERSION= ${ISCVERSION:S/-P/P/:S/b/.b/:S/a/.a/:S/rc/.rc/} <co xml:id="distversion-ex1-portversion"/> +CATEGORIES= dns net ipv6 +MASTER_SITES= ISC/bind9/${ISCVERSION} <co xml:id="distversion-ex1-master_sites"/> +PKGNAMESUFFIX= 99 +DISTNAME= ${PORTNAME}-${ISCVERSION} <co xml:id="distversion-ex1-distname"/> + +MAINTAINER= mat@FreeBSD.org +COMMENT= BIND DNS suite with updated DNSSEC and DNS64 + +LICENSE= ISCL + +# ISC releases things like 9.8.0-P1 or 9.8.1rc1, which our versioning does not like +ISCVERSION= 9.9.9-P6 <co xml:id="distversion-ex1-iscversion"/></programlisting> + + <calloutlist> + <callout arearefs="distversion-ex1-iscversion"> + <para>Defina a versão upstream em <varname>ISCVERSION</varname>, com um comentário dizendo <emphasis>porque</emphasis> é necessário.</para> + </callout> + + <callout arearefs="distversion-ex1-portversion"> + <para>Use <varname>ISCVERSION</varname> para obter um <varname>PORTVERSION</varname> compatível com o ports.</para> + </callout> + + <callout arearefs="distversion-ex1-master_sites"> + <para>Use <varname>ISCVERSION</varname> diretamente para obter a <acronym>URL</acronym> correta para baixar o arquivo de distribuição.</para> + </callout> + + <callout arearefs="distversion-ex1-distname"> + <para>Use <varname>ISCVERSION</varname> diretamente para nomear o arquivo de distribuição.</para> + </callout> + </calloutlist> + </example> + + <example xml:id="makefile-distname-ex2"> + <title>Derivar <varname>DISTNAME</varname> a partir de <varname>PORTVERSION</varname></title> + + <para>De tempos em tempos, o nome do arquivo de distribuição tem pouca ou nenhuma relação com a versão do software.</para> + + <para>No <package role="port">comms/kermit</package>, apenas o último elemento da versão está presente no arquivo de distribuição:</para> + + <programlisting>PORTNAME= kermit +PORTVERSION= 9.0.304 +CATEGORIES= comms ftp net +MASTER_SITES= ftp://ftp.kermitproject.org/kermit/test/tar/ +DISTNAME= cku${PORTVERSION:E}-dev20 <co xml:id="distversion-ex2-distname"/></programlisting> + + <calloutlist> + <callout arearefs="distversion-ex2-distname"> + <para>O modificador <literal>:E</literal> <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> retorna o sufixo da variável, neste caso, <literal>304</literal>. O arquivo de distribuição <literal>cku304-dev20.tar.gz</literal> é gerado corretamente.</para> + </callout> + </calloutlist> + </example> + + <example xml:id="makefile-distname-ex3"> + <title>Caso Exótico 1</title> + + <para>Às vezes, não há relação entre o nome do software, sua versão e o arquivo de distribuição no qual ele é distribuído.</para> + + <para>Do <package role="port">audio/libworkman</package>:</para> + + <programlisting>PORTNAME= libworkman +PORTVERSION= 1.4 +CATEGORIES= audio +MASTER_SITES= LOCAL/jim +DISTNAME= ${PORTNAME}-1999-06-20</programlisting> + </example> + + <example xml:id="makefile-distname-ex4"> + <title>Caso Exótico 2</title> + + <para>No <package role="port">comms/librs232</package>, o arquivo de distribuição não é versionado, portanto, <link linkend="makefile-dist_subdir"><varname>DIST_SUBDIR</varname></link> é necessário:</para> + + <programlisting>PORTNAME= librs232 +PORTVERSION= 20160710 +CATEGORIES= comms +MASTER_SITES= http://www.teuniz.net/RS-232/ +DISTNAME= RS-232 +DIST_SUBDIR= ${PORTNAME}-${PORTVERSION}</programlisting> + </example> + + <note> + <para><varname>PKGNAMEPREFIX</varname> e <varname>PKGNAMESUFFIX</varname> não afetam o <varname>DISTNAME</varname>. Observe também que se <varname>WRKSRC</varname> for igual a <filename>${WRKDIR}/${DISTNAME}</filename> enquanto o arquivo fonte original é nomeado para algo diferente de <literal>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</literal>, deixe <varname>DISTNAME</varname> sozinho— definir apenas <varname>DISTFILES</varname> é mais fácil que ambos <varname>DISTNAME</varname> e <varname>WRKSRC</varname> (e possivelmente <varname>EXTRACT_SUFX</varname>).</para> + </note> + </sect2> + + <sect2 xml:id="makefile-master_sites"> + <title><varname>MASTER_SITES</varname></title> + + <para>Grave a parte do diretório do FTP/HTTP-URL apontando para o tarball original em <varname>MASTER_SITES</varname>. Não esqueça a barra final (<filename>/</filename>)!</para> + + <para>A macro <command>make</command> irá tentar usar esta especificação para baixar o arquivo de distribuição com <varname>FETCH</varname> se não for possível encontrá-lo já no sistema.</para> + + <para>Recomenda-se que vários sites sejam incluídos nesta lista, de preferência em diferentes continentes. Isso irá proteger contra problemas de rede amplos.</para> + + <important> + <para><varname>MASTER_SITES</varname> não deve estar em branco. Ele deve apontar para o site real que hospeda os arquivos de distribuição. Ele não pode apontar para web archives ou para os sites de cache dos arquivos de distribuição do FreeBSD. A única exceção a essa regra são ports que não possuem arquivos de distribuição. Por exemplo, meta-ports não possuem arquivos de distribuição, assim o <varname>MASTER_SITES</varname> não precisa ser definido.</para> + </important> + + <sect3 xml:id="makefile-master_sites-shorthand"> + <title>Usando Variáveis <varname>MASTER_SITE_<replaceable>*</replaceable></varname></title> + + <para>Abreviações de atalhos estão disponíveis para arquivos populares como o SourceForge (<literal>SOURCEFORGE</literal>), GNU (<literal>GNU</literal>), ou Perl CPAN (<literal>PERL_CPAN</literal>). <varname>MASTER_SITES</varname> pode usá-los diretamente:</para> + + <programlisting>MASTER_SITES= GNU/make</programlisting> + + <para>O antigo formato expandido ainda funciona, mas todos os ports foram convertidos para o formato compacto. O formato expandido se parece com isto:</para> + + <programlisting>MASTER_SITES= ${MASTER_SITE_GNU} +MASTER_SITE_SUBDIR= make</programlisting> + + <para>Estes valores e variáveis são definidos em <link xlink:href="https://svnweb.freebsd.org/ports/head/Mk/bsd.sites.mk?view=markup"><filename>Mk/bsd.sites.mk</filename></link>. Novas entradas são adicionadas com frequência, portanto, verifique a versão mais recente deste arquivo antes de enviar um port.</para> + + <tip> + <para>Para qualquer variável <varname>MASTER_SITE_<replaceable>FOO</replaceable></varname> , a versão abreviada <literal><replaceable>FOO</replaceable></literal> pode ser utilizada. Por exemplo, use: </para> + + <programlisting>MASTER_SITES= <replaceable>FOO</replaceable></programlisting> + + <para>E se <varname>MASTER_SITE_SUBDIR</varname> for necessário, use isso:</para> + + <programlisting>MASTER_SITES= <replaceable>FOO</replaceable>/<replaceable>bar</replaceable></programlisting> + </tip> + + <note> + <para>Alguns nomes <varname>MASTER_SITE_<replaceable>*</replaceable></varname> são bastante longos e, para facilitar o uso, foram definidos atalhos:</para> + + <table frame="none" xml:id="makefile-master_sites-shortcut"> + <title>Atalhos para Macros <varname>MASTER_SITE_<replaceable>*</replaceable></varname></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Macro</entry> + <entry>Atalho</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>PERL_CPAN</varname></entry> + <entry><varname>CPAN</varname></entry> + </row> + + <row> + <entry><varname>GITHUB</varname></entry> + <entry><varname>GH</varname></entry> + </row> + + <row> + <entry><varname>GITHUB_CLOUD</varname></entry> + <entry><varname>GHC</varname></entry> + </row> + + <row> + <entry><varname>LIBREOFFICE_DEV</varname></entry> + <entry><varname>LODEV</varname></entry> + </row> + + <row> + <entry><varname>NETLIB</varname></entry> + <entry><varname>NL</varname></entry> + </row> + + <row> + <entry><varname>RUBYGEMS</varname></entry> + <entry><varname>RG</varname></entry> + </row> + + <row> + <entry><varname>SOURCEFORGE</varname></entry> + <entry><varname>SF</varname></entry> + </row> + </tbody> + </tgroup> + </table> + </note> + </sect3> + + <sect3 xml:id="makefile-master_sites-magic"> + <title> Macros Mágicas de MASTER_SITES</title> + + <para>Várias macros <quote>mágicas</quote> existem para sites populares com uma estrutura de diretórios previsível. Para isso, basta usar a abreviação e o sistema escolherá um subdiretório automaticamente. Para um port nomeado <literal>Stardict</literal>, de versão <literal>1.2.3</literal> e hospedado no SourceForge, adicione esta linha:</para> + + <programlisting>MASTER_SITES= SF</programlisting> + + <para>Implica em um subdiretório chamado <literal>/project/stardict/stardict/1.2.3</literal>. Se o diretório estiver incorreto, ele poderá ser substituído:</para> + + <programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> + + <para>Isso também pode ser escrito como</para> + + <programlisting>MASTER_SITES= SF +MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> + + <table frame="none" xml:id="makefile-master_sites-popular"> + <title>Macros Mágicas de <varname>MASTER_SITES</varname></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Macro</entry> + <entry>Subdiretório deduzido</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>APACHE_COMMONS_BINARIES</varname></entry> + <entry><literal>${PORTNAME:S,commons-,,}</literal></entry> + </row> + + <row> + <entry><varname>APACHE_COMMONS_SOURCE</varname></entry> + <entry><literal>${PORTNAME:S,commons-,,}</literal></entry> + </row> + + <row> + <entry><varname>APACHE_JAKARTA</varname></entry> + <entry><literal>${PORTNAME:S,-,/,}/source</literal></entry> + </row> + + <row> + <entry><varname>BERLIOS</varname></entry> + <entry><literal>${PORTNAME:tl}.berlios</literal></entry> + </row> + + <row> + <entry><varname>CHEESESHOP</varname></entry> + <entry><literal>source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</literal></entry> + </row> + + <row> + <entry><varname>CPAN</varname></entry> + <entry><literal>${PORTNAME:C/-.*//}</literal></entry> + </row> + + <row> + <entry><varname>DEBIAN</varname></entry> + <entry><literal>pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>FARSIGHT</varname></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>FESTIVAL</varname></entry> + <entry><literal>${PORTREVISION}</literal></entry> + </row> + + <row> + <entry><varname>GCC</varname></entry> + <entry><literal>releases/${DISTNAME}</literal></entry> + </row> + + <row> + <entry><varname>GENTOO</varname></entry> + <entry><literal>distfiles</literal></entry> + </row> + + <row> + <entry><varname>GIMP</varname></entry> + <entry><literal>${PORTNAME}/${PORTVERSION:R}/</literal></entry> + </row> + + <row> + <entry><varname>GH</varname></entry> + <entry><literal>${GH_ACCOUNT}/${GH_PROJECT}/tar.gz/${GH_TAGNAME}?dummy=/</literal></entry> + </row> + + <row> + <entry><varname>GHC</varname></entry> + <entry><literal>${GH_ACCOUNT}/${GH_PROJECT}/</literal></entry> + </row> + + <row> + <entry><varname>GNOME</varname></entry> + <entry><literal>sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</literal></entry> + </row> + + <row> + <entry><varname>GNU</varname></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>GNUPG</varname></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>GNU_ALPHA</varname></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>HORDE</varname></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>LODEV</varname></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>MATE</varname></entry> + <entry><literal>${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</literal></entry> + </row> + + <row> + <entry><varname>MOZDEV</varname></entry> + <entry><literal>${PORTNAME:tl}</literal></entry> + </row> + + <row> + <entry><varname>NL</varname></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>QT</varname></entry> + <entry><literal>archive/qt/${PORTVERSION:R}</literal></entry> + </row> + + <row> + <entry><varname>SAMBA</varname></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>SAVANNAH</varname></entry> + <entry><literal>${PORTNAME:tl}</literal></entry> + </row> + + <row> + <entry><varname>SF</varname></entry> + <entry><literal>${PORTNAME:tl}/${PORTNAME:tl}/${PORTVERSION}</literal></entry> + </row> + </tbody> + </tgroup> + </table> + </sect3> + </sect2> + + <sect2 xml:id="makefile-master_sites-github"> + <title><varname>USE_GITHUB</varname></title> + + <para>Se o arquivo de distribuição vier de um commit ou tag específico no <link xlink:href="https://github.com">GitHub</link> para o qual não há arquivo lançado oficialmente, há uma maneira fácil de definir o <varname>DISTNAME</varname> e <varname>MASTER_SITES</varname> corretos automaticamente. Estas variáveis estão disponíveis:</para> + + <table xml:id="makefile-master_sites-github-description"> + <title><varname>USE_GITHUB</varname>Descrição</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Variável</entry> + <entry>Descrição</entry> + <entry>Padrão</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>GH_ACCOUNT</varname></entry> + <entry>Nome da conta do usuário do GitHub que hospeda o projeto</entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>GH_PROJECT</varname></entry> + <entry>Nome do projeto no GitHub</entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + + <row> + <entry><varname>GH_TAGNAME</varname></entry> + <entry>Nome da tag para download (2.0.1, hash, ...) Usar o nome de uma branch aqui é errado. Também é possível usar o hash de um ID de commit para gerar um snapshot.</entry> + <entry><literal>${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal></entry> + </row> + + <row> + <entry><varname>GH_SUBDIR</varname></entry> + <entry>Quando o software precisa que um arquivo de distribuição adicional seja extraído em <varname>${WRKSRC}</varname>, esta variável pode ser usada. Veja os exemplos em <xref linkend="makefile-master_sites-github-multiple"/> para maiores informações.</entry> + <entry>(none)</entry> + </row> + + <row> + <entry><varname>GH_TUPLE</varname></entry> + <entry><varname>GH_TUPLE</varname> permite colocar <varname>GH_ACCOUNT</varname>, <varname>GH_PROJECT</varname>, <varname>GH_TAGNAME</varname> e <varname>GH_SUBDIR</varname> em uma única variável. O formato é <replaceable>conta</replaceable><literal>:</literal><replaceable>projeto</replaceable><literal>:</literal><replaceable>tagname</replaceable><literal>:</literal><replaceable>grupo</replaceable><literal>/</literal><replaceable>subdiretório</replaceable>. O <literal>/</literal><replaceable>subdiretório </replaceable> é opcional. Isso é útil quando mais de um projeto no GitHub precisa ser utilizado.</entry> + </row> + </tbody> + </tgroup> + </table> + + <important> + <para>Não use <varname>GH_TUPLE</varname> para o arquivo de distribuição padrão, já que não tem nenhum padrão.</para> + </important> + + <example xml:id="makefile-master_sites-github-ex1"> + <title>Uso Simples de <varname>USE_GITHUB</varname></title> + + <para>Ao tentar fazer um port para a versão <literal>1.2.7</literal> do <application>pkg</application> do usuário FreeBSD no github, em <link xlink:href="https://github.com/freebsd/pkg"/>, O <filename>Makefile</filename> acabaria ficando assim (levemente simplificado para o exemplo):</para> + + <programlisting>PORTNAME= pkg +DISTVERSION= 1.2.7 + +USE_GITHUB= yes +GH_ACCOUNT= freebsd</programlisting> + + <para><varname>MASTER_SITES</varname> será automaticamente definido como <literal>GH GHC</literal> e <varname>WRKSRC</varname> para <literal>${WRKDIR}/pkg-1.2.7</literal>.</para> + </example> + + <example xml:id="makefile-master_sites-github-ex2"> + <title>Uso Mais Completo de <varname>USE_GITHUB</varname></title> + + <para>Ao tentar fazer um port para uma versão de desenvolvimento do <application>pkg</application> do usuário FreeBSD no github, em <link xlink:href="https://github.com/freebsd/pkg"/>, o <filename>Makefile</filename> acaba ficando assim (levemente simplificado para o exemplo):</para> + + <programlisting>PORTNAME= pkg-devel +DISTVERSION= 1.3.0.a.20140411 + +USE_GITHUB= yes +GH_ACCOUNT= freebsd +GH_PROJECT= pkg +GH_TAGNAME= 6dbb17b</programlisting> + + <para><varname>MASTER_SITES</varname> será automaticamente definido para <literal>GH GHC</literal> e <varname>WRKSRC</varname> para <literal>${WRKDIR}/pkg-6dbb17b</literal>.</para> + + <tip> + <para><literal>20140411</literal> é a data do commit referenciada em <varname>GH_TAGNAME</varname>, não a data em que é editado o <filename>Makefile</filename>, ou a data em que o commit é feito. </para> + </tip> + </example> + + <example xml:id="makefile-master_sites-github-ex3"> + <title>Uso de <varname>USE_GITHUB</varname> com <varname>DISTVERSIONPREFIX</varname></title> + + <para>De tempos em tempos, <varname>GH_TAGNAME</varname> é uma ligeira variação de <varname>DISTVERSION</varname>. Por exemplo, se a versão for <literal>1.0.2</literal>, e a tag <literal>v1.0.2</literal>. Nesses casos, é possível usar <varname>DISTVERSIONPREFIX</varname> ou <varname>DISTVERSIONSUFFIX</varname>:</para> + + <programlisting>PORTNAME= foo +DISTVERSIONPREFIX= v +DISTVERSION= 1.0.2 + +USE_GITHUB= yes</programlisting> + + <para><varname>GH_TAGNAME</varname> será automaticamente definido para <literal>v1.0.2</literal>, enquanto <varname>WRKSRC</varname> será mantido como <varname>${WRKDIR} /foo-1.0.2</varname>.</para> + </example> + + <example xml:id="makefile-master_sites-github-ex4"> + <title>Usando <varname>USE_GITHUB</varname> Quando o Upstream Não Usa Versões</title> + + <para>Se nunca houve uma versão upstream, não invente uma como <literal>0.1</literal> ou <literal>1.0</literal>. Crie o port com um <varname>DISTVERSION</varname> de <literal>g<replaceable>YYYY</replaceable><replaceable>MM</replaceable><replaceable>DD</replaceable></literal>, onde <literal>g</literal> é para <application>Git</application> e <literal><replaceable>YYYY</replaceable><replaceable>MM</replaceable><replaceable>DD</replaceable></literal> representa a data em que o commit é referenciado em <varname>GH_TAGNAME</varname>.</para> + + <programlisting>PORTNAME= bar +DISTVERSION= g20140411 + +USE_GITHUB= yes +GH_TAGNAME= c472d66b</programlisting> + + <para>Isso cria um esquema de controle de versão que é incrementado com o tempo e que ainda é menor do que a versão <literal>0</literal> (veja <xref linkend="makefile-versions-ex-pkg-version"/> para mais informações do <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry>): </para> + + <screen><prompt>%</prompt> <userinput>pkg version -t g20140411 0</userinput> +<</screen> + + <para>Isso significa que não será necessário usar o <varname>PORTEPOCH</varname> caso o upstream decida lançar versões no futuro.</para> + </example> + + <example xml:id="makefile-master_sites-github-ex5"> + <title>Usando <varname>USE_GITHUB</varname> para Acessar um Commit Entre Duas Versões</title> + + <para>Se a versão atual do software usa uma tag <application>Git</application>, e o port precisa ser atualizado para uma versão mais recente e intermediária, sem uma tag, use <citerefentry><refentrytitle>git-describe</refentrytitle><manvolnum>1</manvolnum></citerefentry> para descobrir a versão a ser utilizada:</para> + + <screen><prompt>%</prompt> <userinput>git describe --tags <replaceable>f0038b1</replaceable></userinput> +v0.7.3-14-gf0038b1</screen> + + <para><literal>v0.7.3-14-gf0038b1</literal>pode ser dividido em três partes: </para> + + <variablelist> + <varlistentry> + <term><literal>v0.7.3</literal></term> + + <listitem> + <para>Este é a última tag <application>Git</application> que aparece no histórico de commits antes do commit solicitado.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>-14</literal></term> + + <listitem> + <para>Isso significa que o commit solicitado, <literal>f0038b1</literal>, é o 14º commit após a tag <literal>v0.7.3</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>-gf0038b1</literal></term> + + <listitem> + <para>O <literal>-g</literal> significa <quote><application>Git</application></quote>, e o <literal>f0038b1</literal> é o commit hash referenciado.</para> + </listitem> + </varlistentry> + </variablelist> + + <programlisting>PORTNAME= bar +DISTVERSIONPREFIX= v +DISTVERSION= 0.7.3-14 +DISTVERSIONSUFFIX= -gf0038b1 + +USE_GITHUB= yes</programlisting> + + <para>Isso cria um esquema de versionamento que é incrementado com o tempo (bem, em cima de commits), e não entra em conflito com a criação de uma versão <literal>0.7.4</literal>. (Veja <xref linkend="makefile-versions-ex-pkg-version"/> para detalhes do <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry>):</para> + + <screen><prompt>%</prompt> <userinput>pkg version -t 0.7.3 0.7.3.14</userinput> +< +<prompt>%</prompt> <userinput>pkg version -t 0.7.3.14 0.7.4</userinput> +<</screen> + + <note> + <para>Se o commit solicitado é o mesmo que uma tag, uma descrição mais curta é mostrada por padrão. A versão mais longa é equivalente:</para> + + <screen><prompt>%</prompt> <userinput>git describe --tags <replaceable>c66c71d</replaceable></userinput> +v0.7.3 +<prompt>%</prompt> <userinput>git describe --tags --long <replaceable>c66c71d</replaceable></userinput> +v0.7.3-0-gc66c71d</screen> + + </note> + + </example> + + <sect3 xml:id="makefile-master_sites-github-multiple"> + <title>Baixando Múltiplos Arquivos do GitHub</title> + + <para>O framework <varname>USE_GITHUB</varname> também suporta a obtenção de vários arquivos de distribuição de diferentes locais no GitHub. Ele funciona de uma forma muito semelhante ao <xref linkend="porting-master-sites-n"/></para> + + <para>Ao buscar vários arquivos do GitHub, às vezes o arquivo de distribuição padrão não é buscado no GitHub. Para desabilitar a busca da distribuição padrão, defina:</para> + + <programlisting>USE_GITHUB= nodefault</programlisting> + + <para>Vários valores são adicionados a <varname>GH_ACCOUNT</varname>, <varname>GH_PROJECT</varname> e <varname>GH_TAGNAME</varname>. Cada valor diferente é atribuído a um grupo. O valor principal pode não ter nenhum grupo ou grupo <literal>:DEFAULT</literal>. Um valor pode ser omitido se for o mesmo que o padrão listado em <xref linkend="makefile-master_sites-github-description"/></para> + + <para><varname>GH_TUPLE</varname> também pode ser usado quando há muitos arquivos de distribuição. Isso ajuda a manter as informações de conta, projeto, tagname e grupo no mesmo lugar.</para> + + <para>Para cada grupo, uma variável auxiliar <varname>${WRKSRC_<replaceable>group</replaceable>}</varname> é criada, contendo o diretório no qual o arquivo foi extraído. As variáveis <varname>${WRKSRC_<replaceable>group</replaceable>}</varname> podem ser usadas para mover diretórios durante o <buildtarget>post-extract</buildtarget>, ou para serem adicionadas em <varname>CONFIGURE_ARGS</varname>, ou o que for necessário para que o software seja compilado corretamente.</para> + + <caution> + <para>A parte do <literal>:<replaceable>group</replaceable></literal> <emphasis>deve</emphasis> ser usada para <emphasis>apenas um</emphasis> arquivo de distribuição. Ela é usado como uma chave única e usá-la mais de uma vez irá sobrescrever os valores anteriores.</para> + </caution> + + <note> + <para>Como isso é apenas modificações de <varname>DISTFILES</varname> e <varname>MASTER_SITES</varname>, os nomes dos grupos devem obedecer às restrições de nomes de grupos descritas em <xref linkend="porting-master-sites-n"/></para> + </note> + + <example xml:id="makefile-master_sites-github-multi"> + <title>Uso de <varname>USE_GITHUB</varname> com Vários Arquivos de Distribuição </title> + + <para>De tempos em tempos é necessário baixar mais de um arquivo de distribuição. Por exemplo, quando o repositório git do upstream usa submódulos. Isso pode ser feito facilmente usando grupos nas variáveis <varname>GH_<replaceable>*</replaceable></varname>:</para> + + <programlisting>PORTNAME= foo +DISTVERSION= 1.0.2 + +USE_GITHUB= yes +GH_ACCOUNT= bar:icons,contrib +GH_PROJECT= foo-icons:icons foo-contrib:contrib +GH_TAGNAME= 1.0:icons fa579bc:contrib +GH_SUBDIR= ext/icons:icons + +CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}</programlisting> + + <para>Isso irá baixar três arquivos de distribuição do github. O padrão vem de <filename>foo/foo</filename> versão <literal>1.0.2</literal>. O segundo, com o grupo <literal>icons</literal>, vem de <filename>bar/foo-icons</filename> versão <literal>1.0</literal>. O terceiro vem de <filename>bar/foo-contrib</filename> e usa o commit do <application>Git</application><literal>fa579bc</literal>. Os arquivos de distribuição são nomeados <filename>foo-foo-1.0.2_GH0.tar.gz</filename>, <filename>bar-foo-icons-1.0_GH0.tar.gz</filename> e <filename>bar-foo-contrib-fa579bc_GH0.tar.gz</filename>.</para> + + <para>Todos os arquivos de distribuição são extraídos em <varname>${WRKDIR}</varname> em seus respectivos subdiretórios. O arquivo padrão ainda é extraído em <varname>${WRKSRC}</varname>, nesse caso, <filename>${WRKDIR}/foo-1.0.2</filename>. Cada arquivo de distribuição adicional é extraído em <varname>${WRKSRC_<replaceable>group</replaceable>}</varname>. Aqui, para o grupo <literal>icons</literal>, chamado de <varname>${WRKSRC_icons}</varname>, será <filename>${WRKDIR}/foo-icons-1.0</filename>. O arquivo com o grupo <literal>contrib</literal> é chamado de <varname>${WRKSRC_contrib}</varname> e contém <literal>${WRKDIR}/foo-contrib-fa579bc</literal>.</para> + + <para>O sistema de compilação do software espera encontrar os ícones em um subdiretório <filename>ext/icons</filename> em seus fontes, então <varname>GH_SUBDIR</varname> é usado. <varname>GH_SUBDIR</varname> garante que <filename>ext</filename> exista, mas não que <filename>ext/icons</filename> também exista. Então isso acontece:</para> + + <programlisting>post-extract: + @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons</programlisting> + </example> + + <example xml:id="makefile-master_sites-github-multi2"> + <title>Uso de <varname>USE_GITHUB</varname> com Vários Arquivos de Distribuição Usando <varname>GH_TUPLE</varname></title> + + <para>Isto é funcionalmente equivalente a <xref linkend="makefile-master_sites-github-multi"/> mas usando <varname>GH_TUPLE</varname>:</para> + + <programlisting>PORTNAME= foo +DISTVERSION= 1.0.2 + +USE_GITHUB= yes +GH_TUPLE= bar:foo-icons:1.0:icons/ext/icons \ + bar:foo-contrib:fa579bc:contrib + +CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}</programlisting> + + <para>Agrupamento foi usado no exemplo anterior com <literal>bar:icons, contrib</literal>. Algumas informações redundantes estão presentes com <varname>GH_TUPLE</varname> porque o uso de agrupamento não é possível.</para> + </example> + + <example xml:id="makefile-master_sites-github-submodules"> + <title>Como Usar <varname>USE_GITHUB</varname> com Submodulos <application>Git</application>?</title> + + <para>Ports com o GitHub como um repositório upstream às vezes usam submódulos. Veja <citerefentry><refentrytitle>git-submodule</refentrytitle><manvolnum>1</manvolnum></citerefentry> para maiores informações.</para> + + <para>O problema com submódulos é que cada um é um repositório separado. Como tal, cada um deve ser buscado separadamente.</para> + + <para>Usando <package role="port">finances/moneymanagerex</package> como exemplo, seu repositório GitHub é <link xlink:href="https://github.com/moneymanagerex/moneymanagerex"/>. Tem um arquivo <link xlink:href="https://github.com/moneymanagerex/moneymanagerex/blob/master/.gitmodules"><filename>.gitmodules</filename></link> na raiz. Este arquivo descreve todos os sub módulos usados neste repositório e lista os repositórios adicionais necessários. Este arquivo irá dizer quais repositórios adicionais são necessários: </para> + + <programlisting>[submodule "lib/wxsqlite3"] + path = lib/wxsqlite3 + url = https://github.com/utelle/wxsqlite3.git +[submodule "3rd/mongoose"] + path = 3rd/mongoose + url = https://github.com/cesanta/mongoose.git +[submodule "3rd/LuaGlue"] + path = 3rd/LuaGlue + url = https://github.com/moneymanagerex/LuaGlue.git +[submodule "3rd/cgitemplate"] + path = 3rd/cgitemplate + url = https://github.com/moneymanagerex/html-template.git +[...]</programlisting> + + <para>A única informação que falta nesse arquivo é a hash ou tag de commit para usar na versão. Esta informação é encontrada após a clonagem do repositório:</para> + + <screen><prompt>%</prompt> <userinput>git clone --recurse-submodules https://github.com/moneymanagerex/moneymanagerex.git</userinput> +Cloning into 'moneymanagerex'... +remote: Counting objects: 32387, done. +[...] +Submodule '3rd/LuaGlue' (https://github.com/moneymanagerex/LuaGlue.git) registered for path '3rd/LuaGlue' +Submodule '3rd/cgitemplate' (https://github.com/moneymanagerex/html-template.git) registered for path '3rd/cgitemplate' +Submodule '3rd/mongoose' (https://github.com/cesanta/mongoose.git) registered for path '3rd/mongoose' +Submodule 'lib/wxsqlite3' (https://github.com/utelle/wxsqlite3.git) registered for path 'lib/wxsqlite3' +[...] +Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/LuaGlue'... +Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/cgitemplate'... +Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/3rd/mongoose'... +Cloning into '/home/mat/work/freebsd/ports/finance/moneymanagerex/moneymanagerex/lib/wxsqlite3'... +[...] +Submodule path '3rd/LuaGlue': checked out 'c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b' +Submodule path '3rd/cgitemplate': checked out 'cd434eeeb35904ebcd3d718ba29c281a649b192c' +Submodule path '3rd/mongoose': checked out '2140e5992ab9a3a9a34ce9a281abf57f00f95cda' +Submodule path 'lib/wxsqlite3': checked out 'fb66eb230d8aed21dec273b38c7c054dcb7d6b51' +[...] +<prompt>%</prompt> <userinput>cd moneymanagerex</userinput> +<prompt>%</prompt> <userinput>git submodule status</userinput> + c51d11a247ee4d1e9817dfa2a8da8d9e2f97ae3b 3rd/LuaGlue (heads/master) + cd434eeeb35904ebcd3d718ba29c281a649b192c 3rd/cgitemplate (cd434ee) + 2140e5992ab9a3a9a34ce9a281abf57f00f95cda 3rd/mongoose (6.2-138-g2140e59) + fb66eb230d8aed21dec273b38c7c054dcb7d6b51 lib/wxsqlite3 (v3.4.0) +[...]</screen> + + <para>Também pode ser encontrado no GitHub. Cada subdiretório que é um submódulo é mostrado como <replaceable>diretório</replaceable> <literal> @ </literal><replaceable>hash</replaceable>, por exemplo,<literal>mongoose @ 2140e59</literal>.</para> + + <note> + <para>Embora a obtenção das informações pelo GitHub pareça mais fácil, as informações encontradas usando <command>git submodule status</command> fornecerá informações mais significativas. Por exemplo, o commit hash de <literal>lib/wxsqlite3</literal> <literal>fb66eb2</literal> corresponde a <literal>v3.4.0</literal>. Ambos podem ser usados, mas quando uma tag estiver disponível, use-a.</para> + </note> + + <para>Agora que todas as informações necessárias foram reunidas, o <filename>Makefile</filename> pode ser escrito (somente as linhas relacionadas ao GitHub são mostradas):</para> + + <programlisting>PORTNAME= moneymanagerex +DISTVERSIONPREFIX= v +DISTVERSION= 1.3.0 + +USE_GITHUB= yes +GH_TUPLE= utelle:wxsqlite3:v3.4.0:wxsqlite3/lib/wxsqlite3 \ + moneymanagerex:LuaGlue:c51d11a:lua_glue/3rd/LuaGlue \ + moneymanagerex:html-template:cd434ee:html_template/3rd/cgitemplate \ + cesanta:mongoose:2140e59:mongoose/3rd/mongoose \ + [...]</programlisting> + </example> + </sect3> + </sect2> + + <sect2 xml:id="makefile-master_sites-gitlab"> + <title><varname>USE_GITLAB</varname></title> + + <para>Semelhante ao GitHub, se o arquivo de distribuição vier de <link xlink:href="https://gitlab.com">gitlab.com</link> ou se estiver hospedado com o software <application>GitLab</application>, essas variáveis estão disponíveis para uso e talvez precisem ser definidas. </para> + + <table xml:id="makefile-master_sites-gitlab-description"> + <title><varname>USE_GITLAB</varname> Descrição</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Variável</entry> + <entry>Descrição</entry> + <entry>Padrão</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>GL_SITE</varname></entry> + <entry>Nome do site que hospeda o projeto <application>GitLab</application></entry> <entry>https://gitlab.com</entry> + </row> + + <row> + <entry><varname>GL_ACCOUNT</varname></entry> + <entry>Nome da conta do usuário do <application>GitLab</application> hospedando o projeto </entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>GL_PROJECT</varname></entry> + <entry>Nome do projeto em <application>GitLab</application></entry> + <entry><literal>${PORTNAME}</literal></entry> + </row> + + <row> + <entry><varname>GL_COMMIT</varname></entry> + <entry>O hash de commit para download. Deve ser o hash hex sha1 completo de 160 bits e 40 caracteres. Essa é uma variável obrigatória para <application>GitLab</application>.</entry> + <entry><literal>(none)</literal></entry> + </row> + + <row> + <entry><varname>GL_SUBDIR</varname></entry> + <entry>Quando o software precisa de um arquivo de distribuição adicional para ser extraído com <varname>${WRKSRC}</varname>, esta variável pode ser usada. Veja os exemplos em <xref linkend="makefile-master_sites-gitlab-multiple"/> para maiores informações.</entry> + <entry>(none)</entry> + </row> + + <row> + <entry><varname>GL_TUPLE</varname></entry> + <entry><varname>GL_TUPLE</varname> permite colocar <varname>GL_SITE</varname>, <varname>GL_ACCOUNT</varname>, <varname>GL_PROJECT</varname>, <varname>GL_COMMIT</varname>, e <varname>GL_SUBDIR</varname> dentro de uma única variável. O formato é <replaceable>site</replaceable><literal>:</literal><replaceable>conta</replaceable><literal>:</literal><replaceable>projeto</replaceable><literal>:</literal><replaceable>commit</replaceable><literal>:</literal><replaceable>grupo</replaceable><literal>/</literal><replaceable>subdiretório</replaceable>. O <replaceable>site</replaceable><literal>:</literal> e <literal>/</literal><replaceable>subdiretório</replaceable> são opcionais. Isso ajuda quando é necessário baixar arquivos de mais de um projeto <application>GitLab</application>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="makefile-master_sites-gitlab-ex1"> + <title>Uso Simples de <varname>USE_GITLAB</varname></title> + + <para>Ao tentar fazer um port para a versão <literal>1.14</literal> do <application>libsignon-glib</application> do usuário accounts-sso do gitlab.com, em <link xlink:href="https://gitlab.com/accounts-sso/libsignon-glib"/>, O <filename>Makefile</filename> acabaria ficando assim para buscar os arquivos de distribuição:</para> + + <programlisting>PORTNAME= libsignon-glib +DISTVERSION= 1.14 + +USE_GITLAB= yes +GL_ACCOUNT= accounts-sso +GL_COMMIT= e90302e342bfd27bc8c9132ab9d0ea3d8723fd03</programlisting> + + <para>Ele terá automaticamente <varname>MASTER_SITES</varname> definido como <link xlink:href="https://gitlab.com">gitlab.com</link> e <varname>WRKSRC</varname> para <literal>${WRKDIR}/libsignon-glib-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03-e90302e342bfd27bc8c9132ab9d0ea3d8723fd03</literal>.</para> + </example> + + <example xml:id="makefile-master_sites-gitlab-ex2"> + <title>Uso Mais Completo de <varname>USE_GITLAB</varname></title> + + <para>Um uso mais completo do exemplo acima é se o port não tiver controle de versão e <application>foobar</application> do usuário foo no projeto bar em um <application>GitLab</application> auto hospedado em <literal>https://gitlab.example.com</literal>, o <filename>Makefile</filename> acaba ficando assim para buscar os arquivos de distribuição: </para> + + <programlisting>PORTNAME= foobar +DISTVERSION= g20170906 + +USE_GITLAB= yes +GL_SITE= https://gitlab.example.com +GL_ACCOUNT= foo +GL_PROJECT= bar +GL_COMMIT= 9c1669ce60c3f4f5eb43df874d7314483fb3f8a6</programlisting> + + <para>Terá <varname>MASTER_SITES</varname> definido como "<literal>https://gitlab.example.com</literal>" e <varname>WRKSRC</varname> para <literal>${WRKDIR}/bar-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6</literal>.</para> + + <tip> + <para><literal>20170906</literal> é a data do commit referenciada em <varname>GL_COMMIT</varname>, não a data em que o <filename>Makefile</filename> é editado, ou a data em que o commit para a árvore de ports do FreeBSD é feito.</para> + </tip> + + <note> + <para>O protocolo, porta e webroot do <varname>GL_SITE</varname> podem ser modificados na mesma variável.</para> + </note> + </example> + + <sect3 xml:id="makefile-master_sites-gitlab-multiple"> + <title>Baixando Múltiplos Arquivos do <application>GitLab</application></title> + + <para>O framework <varname>USE_GITLAB</varname> também suporta a busca de vários arquivos de distribuição de diferentes locais de <application>GitLab</application> e sites hospedados no <application>GitLab</application>. Ele funciona de uma forma muito semelhante ao <xref linkend="porting-master-sites-n"/> e <xref linkend="makefile-master_sites-gitlab-multiple"/>.</para> + + <para>Ao buscar vários arquivos usando <application>GitLab</application>, às vezes, o arquivo de distribuição padrão não é obtido de um <application>GitLab</application>. Para desativar a busca do arquivo de distribuição padrão, defina:</para> + + <programlisting>USE_GITLAB= nodefault</programlisting> + + <para>Vários valores são adicionados a <varname>GL_SITE</varname>, <varname>GL_ACCOUNT</varname>, <varname>GL_PROJECT</varname> e <varname>GL_COMMIT</varname>. Cada valor diferente é atribuído a um grupo. <xref linkend="makefile-master_sites-gitlab-description"/>.</para> + + <para><varname>GL_TUPLE</varname> também pode ser usado quando há muitos arquivos de distribuição. Isso ajuda a manter as informações de site, conta, projeto, commit e grupo no mesmo local.</para> + + <para>Para cada grupo, uma variável auxiliar <varname>${WRKSRC_<replaceable>group</replaceable>}</varname> é criada, contendo o diretório no qual o arquivo foi extraído. As variáveis <varname>${WRKSRC_<replaceable>group</replaceable>}</varname> podem ser usadas para mover diretórios durante o <buildtarget>post-extract</buildtarget>, ou para serem adicionadas em <varname>CONFIGURE_ARGS</varname>, ou o que for necessário para que o software seja compilado corretamente.</para> + + <caution> + <para>A parte do <literal>:<replaceable>group</replaceable></literal> <emphasis>deve</emphasis> ser usada para <emphasis>apenas um</emphasis> arquivo de distribuição. Ela é usado como uma chave única e usá-la mais de uma vez irá sobrescrever os valores anteriores.</para> + </caution> + + <note> + <para>Como isso é apenas modificações de <varname>DISTFILES</varname> e <varname>MASTER_SITES</varname>, os nomes dos grupos devem obedecer às restrições de nomes de grupos descritas em <xref linkend="porting-master-sites-n"/></para> + </note> + + <example xml:id="makefile-master_sites-gitlab-multi"> + <title>Uso de <varname>USE_GITLAB</varname> com Vários Arquivos de Distribuição</title> + + <para>De tempos em tempos, é necessário buscar mais de um arquivo de distribuição. Por exemplo, quando o repositório git do upstream usa submódulos. Isso pode ser feito facilmente usando grupos nas variáveis <varname>GL_<replaceable>*</replaceable></varname>:</para> + + <programlisting>PORTNAME= foo +DISTVERSION= 1.0.2 + +USE_GITLAB= yes +GL_SITE= https://gitlab.example.com:9434/gitlab:icons +GL_ACCOUNT= bar:icons,contrib +GL_PROJECT= foo-icons:icons foo-contrib:contrib +GL_COMMIT= c189207a55da45305c884fe2b50e086fcad4724b ae7368cab1ca7ca754b38d49da064df87968ffe4:icons 9e4dd76ad9b38f33fdb417a4c01935958d5acd2a:contrib +GL_SUBDIR= ext/icons:icons + +CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}</programlisting> + + <para>Isso irá buscar dois arquivos de distribuição do gitlab.com e um de <literal>gitlab.example.com</literal> hospedado com <application>GitLab</application>. O padrão vem de <filename>https://gitlab.com/foo/foo</filename> e o commit é <literal>c189207a55da45305c884fe2b50e086fcad4724b</literal>. O segundo, com o grupo <literal>icons</literal>, vem de <filename>https://gitlab.example.com:9434/gitlab/bar/foo-icons</filename> e o commit é <literal>ae7368cab1ca7ca754b38d49da064df87968ffe4</literal>. O terceiro vem de <filename>https://gitlab.com/bar/foo-contrib</filename> e o commit é <literal>9e4dd76ad9b38f33fdb417a4c01935958d5acd2a</literal>. Os arquivos de distribuição são nomeados <filename>foo-foo-c189207a55da45305c884fe2b50e086fcad4724b_GL0.tar.gz</filename>, <filename>bar-foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4_GL0.tar.gz</filename> e <filename>bar-foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a_GL0.tar.gz</filename>.</para> + + <para>Todos os arquivos de distribuição são extraídos no <varname>${WRKDIR}</varname> em seus respectivos subdiretórios. O arquivo padrão ainda é extraído no <varname>${WRKSRC}</varname>, nesse caso, <filename>${WRKDIR}/foo-c189207a55da45305c884fe2b50e086fcad4724b-c189207a55da45305c884fe2b50e086fcad4724b</filename>. Cada arquivo de distribuição adicional é extraído em <varname>${WRKSRC_<replaceable>group</replaceable>}</varname>. Aqui, para o grupo <literal>icons</literal>, é chamado <varname>${WRKSRC_icons}</varname> e contém <filename>${WRKDIR}/foo-icons-ae7368cab1ca7ca754b38d49da064df87968ffe4-ae7368cab1ca7ca754b38d49da064df87968ffe4</filename>. O arquivo com o grupo <literal>contrib</literal> é chamado <varname>${WRKSRC_contrib}</varname> e contém <literal>${WRKDIR}/foo-contrib-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a-9e4dd76ad9b38f33fdb417a4c01935958d5acd2a</literal>.</para> + + <para>O sistema de compilação do software espera encontrar os ícones em um subdiretório <filename>ext/icons</filename> em seus fontes, então <varname>GL_SUBDIR</varname> é usado.<varname>GL_SUBDIR</varname> garante que <filename>ext</filename> existe, mas não que <filename>ext/icons</filename> também exista. Então isso acontece: </para> + + <programlisting>post-extract: + @${MV} ${WRKSRC_icons} ${WRKSRC}/ext/icons</programlisting> + </example> + + <example xml:id="makefile-master_sites-gitlab-multi2"> + <title>Uso de <varname>USE_GITLAB</varname> com Vários Arquivos de Distribuição Usando <varname>GL_TUPLE</varname></title> + + <para>Isto é funcionalmente equivalente a <xref linkend="makefile-master_sites-gitlab-multi"/> mas usando <varname>GL_TUPLE</varname>: </para> + + <programlisting>PORTNAME= foo +DISTVERSION= 1.0.2 + +USE_GITLAB= yes +GL_COMMIT= c189207a55da45305c884fe2b50e086fcad4724b +GL_TUPLE= https://gitlab.example.com:9434/gitlab:bar:foo-icons:ae7368cab1ca7ca754b38d49da064df87968ffe4:icons/ext/icons \ + bar:foo-contrib:9e4dd76ad9b38f33fdb417a4c01935958d5acd2a:contrib + +CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}</programlisting> + + <para>Agrupamento foi usado no exemplo anterior com <literal>bar:icons,contrib</literal>. Algumas informações redundantes estão presentes com <varname>GL_TUPLE</varname> porque o uso de agrupamento não é possível.</para> + </example> + </sect3> + </sect2> + + <sect2 xml:id="makefile-extract_sufx"> + <title><varname>EXTRACT_SUFX</varname></title> + + <para>Se houver um arquivo de distribuição e ele usar um sufixo diferente para indicar o mecanismo de compactação, defina <varname>EXTRACT_SUFX</varname>.</para> + + <para>Por exemplo, se o arquivo de distribuição foi nomeado <filename>foo.tar.gzip</filename> em vez do mais comum <filename>foo.tar.gz</filename>, escreva:</para> + + <programlisting>DISTNAME= foo +EXTRACT_SUFX= .tar.gzip</programlisting> + + <para>O <literal>USES=tar[:<replaceable>xxx</replaceable>]</literal>, <literal>USES=lha</literal> ou <literal>USES=zip</literal> define automaticamente <varname>EXTRACT_SUFX</varname> com as extensões de arquivo mais comuns, conforme necessário, consulte <xref linkend="uses"/> para mais detalhes. Se nenhum destes estiver definido, o <varname>EXTRACT_SUFX</varname> padrão é <literal>.tar.gz</literal>.</para> + + <note> + <para>Como <varname>EXTRACT_SUFX</varname> é usado apenas em <varname>DISTFILES</varname>, apenas defina um deles..</para> + </note> + </sect2> + + <sect2 xml:id="makefile-distfiles-definition"> + <title><varname>DISTFILES</varname></title> + + <para>Às vezes os nomes dos arquivos a serem baixados não têm semelhança com o nome do port. Por exemplo, pode ser chamado <filename>source.tar.gz</filename> ou similar. Em outros casos, o código-fonte do aplicativo pode estar em vários arquivos diferentes, e todos eles devem ser baixados. </para> + + <para>Se este for o caso, defina <varname>DISTFILES</varname> para ser uma lista separada por espaços de todos os arquivos que devem ser baixados. </para> + + <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting> + + <para>Se não for definido explicitamente, o <varname>DISTFILES</varname> padrão é <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para> + </sect2> + + <sect2 xml:id="makefile-extract_only"> + <title><varname>EXTRACT_ONLY</varname></title> + + <para>Se apenas alguns dos <varname>DISTFILES</varname> devem ser extraídos— por exemplo, um deles é o código-fonte, enquanto outro é um documento não compactado - liste os nomes dos arquivos que devem ser extraídos em <varname>EXTRACT_ONLY</varname>.</para> + + <programlisting>DISTFILES= source.tar.gz manual.html +EXTRACT_ONLY= source.tar.gz</programlisting> + + <para>Quando nenhum dos <varname>DISTFILES</varname> precisam ser descompactados, deixe vazio o <varname>EXTRACT_ONLY</varname>.</para> + + <programlisting>EXTRACT_ONLY=</programlisting> + </sect2> + + <sect2 xml:id="porting-patchfiles"> + <title><varname>PATCHFILES</varname></title> + + <para>Se o port requer alguns patches adicionais que estão disponíveis por <acronym>FTP</acronym> ou <acronym>HTTP</acronym>, defina <varname>PATCHFILES</varname> para os nomes dos arquivos e <varname>PATCH_SITES</varname> para a URL do diretório que os contém (o formato é o mesmo do <varname>MASTER_SITES</varname>).</para> + + <para>Se o patch não for relativo ao inicio da árvore do código fonte (isto é, <varname>WRKSRC</varname>) porque contém alguns pathnames extras, defina <varname>PATCH_DIST_STRIP</varname> adequadamente. Por exemplo, se todos os pathnames no patch tiverem um <literal>foozolix-1.0 /</literal> extra na frente dos nomes dos arquivos, então defina <literal>PATCH_DIST_STRIP=-p1</literal>.</para> + + <para>Não se preocupe se os patches estiverem compactados; eles serão descompactados automaticamente se os nomes dos arquivos terminarem com <filename>.Z</filename>, <filename>.gz</filename>, <filename>.bz2</filename> ou <filename>.xz</filename>.</para> + + <para>Se o patch for distribuído com alguns outros arquivos, como documentação, em um arquivo compactado, o uso de <varname>PATCHFILES</varname> não será possível. Se for esse o caso, adicione o nome e a localização do arquivo do patch em <varname>DISTFILES</varname> e <varname>MASTER_SITES</varname>. Então, use <varname>EXTRA_PATCHES</varname> para apontar para esses arquivos e o <filename>bsd.port.mk</filename> irá aplicá-los automaticamente. Em particular, <emphasis>não</emphasis> copie os arquivos de patch em <filename>${PATCHDIR}</filename>. Esse diretório pode não ter permissão de escrita. </para> + + <tip> + <para>Se houver vários patches e eles precisarem de valores mistos para o parâmetro strip, ele poderá ser adicionado ao lado do nome do patch em <varname>PATCHFILES</varname>, por exemplo:</para> + + <programlisting>PATCHFILES= patch1 patch2:-p1</programlisting> + + <para>Isto não entra em conflito com <link linkend="porting-master-sites-n"> o recurso de agrupamento de sites principais</link>, adicionando um grupo também funciona: </para> + + <programlisting>PATCHFILES= patch2:-p1:source2</programlisting> + </tip> + + <note> + <para>O arquivo será extraído junto com o arquivo de código fonte, então não há necessidade de explicitamente extraí-lo se ele for um arquivo compactado normal. Tome cuidado extra para não sobrescrever algo que já existe nesse diretório caso faça a extração manualmente. Também não se esqueça de adicionar um comando para remover o patch copiado no target <buildtarget>pre-clean</buildtarget>.</para> + </note> + </sect2> + + <sect2 xml:id="porting-master-sites-n"> + <title>Múltiplos Arquivos de Distribuição ou Patches de Vários Locais</title> + + <para>(Considere isto como um <quote>tópico avançado</quote>; a princípio, aqueles que são novos neste documento podem desejar pular esta seção).</para> + + <para>Esta seção contém informações sobre o mecanismo de busca conhecido como <literal>MASTER_SITES:n</literal> e <literal>MASTER_SITES_NN</literal>. Vamos nos referir a este mecanismo como <literal>MASTER_SITES:n</literal></para> + + <para>Um pouco de background primeiro. O OpenBSD tem um ótimo recurso dentro do <varname>DISTFILES</varname> e <varname>PATCHFILES</varname> que permite que arquivos e pacthes sejam pós fixados com identificadores <literal>:n</literal>. Aqui, <literal>n</literal> pode ser qualquer palavra que contenha <literal>[0-9a-zA-Z_]</literal> e signifique uma designação de grupo. Por exemplo:</para> + + <programlisting>DISTFILES= alpha:0 beta:1</programlisting> + + <para>No OpenBSD, arquivo de distribuição <filename>alpha</filename> será associado com a variável <varname>MASTER_SITES0</varname> em vez da nossa comum <varname>MASTER_SITES</varname> e <filename>beta</filename> com <varname>MASTER_SITES1</varname>.</para> + + <para>Esta é uma característica muito interessante que pode diminuir a busca sem fim pelo site de download correto.</para> + + <para>Apenas imagine 2 arquivos em <varname>DISTFILES</varname> e 20 sites em <varname>MASTER_SITES</varname>, os sites são extremamente lentos e <filename>beta</filename> é hospedado em todas as entradas do <varname>MASTER_SITES</varname> e <filename>alfa</filename> só pode ser encontrado no 20º site. Seria um desperdício checar todos eles se o mantenedor soubesse isso de antemão, não seria? Não é um bom começo para aquele lindo fim de semana!</para> + + <para>Agora que você já tem uma ideia, imagine mais <varname>DISTFILES</varname> e mais <varname>MASTER_SITES</varname>. Certamente nosso <quote>distfiles survey meister</quote> irá ser apreciado pelo alívio nas conexões de rede que isso trará.</para> + + <para>Nas próximas seções, as informações seguirão a implementação do FreeBSD desta idéia. Nós melhoramos um pouco o conceito do OpenBSD.</para> + + <important> + <para>Os nomes dos grupos não podem ter traços neles (<literal>-</literal>), na verdade, eles não podem ter nenhum caractere fora do range <literal>[a-zA-Z0-9_]</literal>. Isso porque, enquanto<citerefentry><refentrytitle> make</refentrytitle><manvolnum>1</manvolnum></citerefentry> está ok com nomes de variáveis contendo traços, <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>não.</para> + </important> + + <sect3 xml:id="porting-master-sites-n-simplified"> + <title>Informação Simplificada</title> + + <para>Esta seção explica como preparar rapidamente a busca de vários arquivos de distribuição e patches de diferentes sites e subdiretórios. Descrevemos aqui um caso de uso de <literal>MASTER_SITES:n</literal>. Isso será suficiente para a maioria dos cenários. Informações mais detalhadas estão disponíveis em <xref linkend="ports-master-sites-n-detailed"/>.</para> + + <para>Alguns aplicativos consistem em vários arquivos de distribuição que devem ser baixados de vários sites diferentes. Por exemplo, <application>Ghostscript</application> consiste no núcleo do programa e, em seguida, um grande número de arquivos de driver que são usados dependendo da impressora do usuário. Alguns desses arquivos de driver são fornecidos com o núcleo, mas muitos outros devem ser baixados de uma variedade de sites diferentes. </para> + + <para>Para suportar isso, cada entrada no <varname>DISTFILES</varname> pode ser seguida por dois pontos e um <quote>nome de grupo</quote>. Cada site listado em <varname>MASTER_SITES</varname> é então seguido por dois pontos, e o grupo que indica quais arquivos de distribuição são baixados deste site.</para> + + <para>Por exemplo, considere um aplicativo com a divisão do código fonte em duas partes, <filename>source1.tar.gz</filename> e <filename>source2.tar.gz</filename>, que deve ser baixado de dois sites diferentes. O <filename>Makefile</filename> do port incluiria linhas como <xref linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/></para> + + <example xml:id="ports-master-sites-n-example-simple-use-one-file-per-site"> + + <title>Uso Simplificado de <literal>MASTER_SITES:n</literal> com Um Arquivo Por Site</title> + + <programlisting>MASTER_SITES= ftp://ftp1.example.com/:source1 \ + http://www.example.com/:source2 +DISTFILES= source1.tar.gz:source1 \ + source2.tar.gz:source2</programlisting> + </example> + + <para>Vários arquivos de distribuição podem ter o mesmo grupo. Continuando o exemplo anterior, suponha que houvesse um terceiro distfile, <filename>source3.tar.gz</filename>, que é baixado do <systemitem>ftp.example2.com</systemitem>. O <filename>Makefile</filename> seria então escrito como <xref linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para> + + <example xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> + + <title>Uso Simplificado de <literal>MASTER_SITES:n</literal> com Mais de Um Arquivo Por Site</title> + + <programlisting>MASTER_SITES= ftp://ftp.example.com/:source1 \ + http://www.example.com/:source2 +DISTFILES= source1.tar.gz:source1 \ + source2.tar.gz:source2 \ + source3.tar.gz:source2</programlisting> + </example> + </sect3> + + <sect3 xml:id="ports-master-sites-n-detailed"> + <title>Informação Detalhada</title> + + <para>Ok, então o exemplo anterior não refletiu as necessidades do novo port? Nesta seção vamos explicar em detalhes como o mecanismo de busca avançado <literal>MASTER_SITES:n</literal> funciona e como ele pode ser usado.</para> + + <orderedlist> + <listitem> + <para>Elementos podem ser pós-fixados com <literal>:<replaceable>n</replaceable></literal> onde <replaceable>n</replaceable> é <literal>[^:,]+</literal>, isso é, <replaceable>n</replaceable> poderia conceitualmente ser qualquer string alfanumérica, mas vamos limitá-lo a <literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> por enquanto.</para> + + <para>Além disso, a verificação de strings é case sensitive, ou seja, <literal>n</literal> é diferente de <literal>N</literal>.</para> + + <para>No entanto, essas palavras não podem ser usadas para finalidades de pós-fixação, pois elas produzem um significado especial: <literal>default</literal>, <literal>all</literal> e <literal>ALL</literal> (estes são usados internamente no item <xref linkend="porting-master-sites-n-what-changes-in-port-targets"/>). Além disso, <literal>DEFAULT</literal> é uma palavra de propósito especial (verifique o item <xref linkend="porting-master-sites-n-DEFAULT-group"/>).</para> + </listitem> + + <listitem> + <para>Elementos pós-fixados com <literal>:n</literal> pertence ao grupo <literal>n</literal>, <literal>:m</literal> pertence ao grupo <literal>m</literal> e assim por diante.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-DEFAULT-group"> + <para>Elementos que não estão pós-fixados são desagrupados, todos eles pertencem ao grupo especial <literal>DEFAULT</literal>. Quaisquer elementos pós-fixados com <literal>DEFAULT</literal> estão apenas sendo redundantes, a menos que um elemento pertença a ambos <literal>DEFAULT</literal> e outros grupos ao mesmo tempo (verifique o item <xref linkend="porting-master-sites-n-comma-operator"/>).</para> + + <para>Esses exemplos são equivalentes, mas o primeiro é o preferido:</para> + + <programlisting>MASTER_SITES= alpha</programlisting> + + <programlisting>MASTER_SITES= alpha:DEFAULT</programlisting> + </listitem> + + <listitem> + <para>Grupos não são exclusivos, um elemento pode pertencer a vários grupos diferentes ao mesmo tempo e um grupo pode ter vários elementos diferentes ou nenhum.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-comma-operator"> + <para>Quando um elemento pertence a vários grupos ao mesmo tempo, use uma vírgula (<literal>, </literal>).</para> + + <para>Em vez de repetir isso várias vezes, cada vez com uma pós-fixação diferente, podemos listar vários grupos de uma vez em uma única pós-fixação. Por exemplo, <literal>:m,n,o</literal> marca um elemento que pertence ao grupo <literal>m</literal>, <literal>n</literal> e <literal>o</literal>.</para> + + <para>Todos esses exemplos são equivalentes, mas o último é o preferido:</para> + + <programlisting>MASTER_SITES= alpha alpha:SOME_SITE</programlisting> + + <programlisting>MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE</programlisting> + + <programlisting>MASTER_SITES= alpha:SOME_SITE,DEFAULT</programlisting> + + <programlisting>MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting> + </listitem> + + <listitem> + <para>Todos os sites dentro de um determinado grupo são ordernados de acordo com <varname>MASTER_SORT_AWK</varname>. Todos os grupos dentro de <varname>MASTER_SITES</varname> e <varname>PATCH_SITES</varname> são ordenados também. </para> + </listitem> + + <listitem xml:id="porting-master-sites-n-group-semantics"> + <para>A semântica de grupo pode ser usada em qualquer uma das variáveis <varname>MASTER_SITES</varname>, <varname>PATCH_SITES</varname>, <varname>MASTER_SITE_SUBDIR</varname>, <varname>PATCH_SITE_SUBDIR</varname>, <varname>DISTFILES</varname> e <varname>PATCHFILES</varname> de acordo com esta sintaxe: </para> + + <orderedlist> + <listitem> + <para>Todos elementos <varname>MASTER_SITES</varname>, <varname>PATCH_SITES</varname>, <varname>MASTER_SITE_SUBDIR</varname> e <varname>PATCH_SITE_SUBDIR</varname> devem ser terminados com o caractere barra <literal>/</literal>. Se algum elemento pertencer a algum grupo, o grupo de pós-fixação <literal>:<replaceable>n</replaceable></literal> deve vir logo após o terminador <literal>/</literal>. O mecanismo <literal>MASTER_SITES:n</literal> depende da existência do terminador <literal>/</literal> para evitar confundir elementos onde um <literal>:n</literal> é uma parte válida do elemento com ocorrências em que <literal>:n</literal> denota grupo <literal>n</literal>. Para fins de compatibilidade, uma vez que o terminador <literal>/</literal> não for necessário antes em ambos elementos <varname>MASTER_SITE_SUBDIR</varname> e <varname>PATCH_SITE_SUBDIR</varname>, se o caractere precedente imediato da pós-fixação não for <literal>/</literal> então <literal>:n</literal> será considerada uma parte válida do elemento em vez de uma pós-fixação de grupo, mesmo que um elemento <literal>n</literal> seja pós-fixado. Veja ambos <xref linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/> e <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/></para> + + <example xml:id="ports-master-sites-n-example-detailed-use-master-site-subdir"> + + <title>Uso Detalhado de <literal>MASTER_SITES:n</literal> no <varname>MASTER_SITE_SUBDIR</varname></title> + + <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting> + + <itemizedlist> + <listitem> + <para>Diretórios dentro do grupo <literal>DEFAULT</literal> -> old:n</para> + </listitem> + + <listitem> + <para>Diretórios dentro do grupo <literal>NEW</literal> -> new</para> + </listitem> + </itemizedlist> + </example> + + <example xml:id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> + + <title>Uso Detalhado de <literal>MASTER_SITES:n</literal> com Vírgula, Vários Arquivos, Vários Sites e Vários Subdiretórios</title> + + <programlisting>MASTER_SITES= http://site1/%SUBDIR%/http://site2/:DEFAULT \ + http://site3/:group3 http://site4/:group4 \ + http://site5/:group5 http://site6/:group6 \ + http://site7/:DEFAULT,group6 \ + http://site8/%SUBDIR%/:group6,group7 \ + http://site9/:group8 +DISTFILES= file1 file2:DEFAULT file3:group3 \ + file4:group4,group5,group6 file5:grouping \ + file6:group7 +MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ + directory-one/:group6,DEFAULT \ + directory</programlisting> + + <para>O exemplo anterior resulta em uma busca detalhada. Os sites são listados na ordem exata em que serão usados.</para> + + <itemizedlist> + <listitem> + <para><filename>arquivo1</filename> será obtido a partir de</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site1/directory-trial:1/</para> + </listitem> + + <listitem> + <para>http://site1/directory-one/</para> + </listitem> + + <listitem> + <para>http://site1/directory/</para> + </listitem> + + <listitem> + <para>http://site2/</para> + </listitem> + + <listitem> + <para>http://site7/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>arquivo2</filename> será baixado exatamente como o <filename>arquivo1</filename> já que ambos pertencem ao mesmo grupo </para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site1/directory-trial:1/</para> + </listitem> + + <listitem> + <para>http://site1/directory-one/</para> + </listitem> + + <listitem> + <para>http://site1/directory/</para> + </listitem> + + <listitem> + <para>http://site2/</para> + </listitem> + + <listitem> + <para>http://site7/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>arquivo3</filename> será obtido a partir de</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site3/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>arquivo4</filename> será obtido a partir de</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site4/</para> + </listitem> + + <listitem> + <para>http://site5/</para> + </listitem> + + <listitem> + <para>http://site6/</para> + </listitem> + + <listitem> + <para>http://site7/</para> + </listitem> + + <listitem> + <para>http://site8/directory-one/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>arquivo5</filename> será obtido a partir de </para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>file6</filename> será obtido a partir de</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site8/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </example> + </listitem> + </orderedlist> + </listitem> + + <listitem> + <para>Como posso agrupar uma das macros especiais de <filename>bsd.sites.mk</filename>, por exemplo, SourceForge (<literal>SF</literal>)?</para> + + <para>Isso foi simplificado o máximo possível. Veja <xref linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para> + + <example xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> + + <title>Uso Detalhado de <literal>MASTER_SITES:n</literal> com SourceForge (<literal>SF</literal>)</title> + + <programlisting>MASTER_SITES= http://site1/SF/something/1.0:sourceforge,TEST +DISTFILES= something.tar.gz:sourceforge</programlisting> + + <para><filename>something.tar.gz</filename> será obtido por todos os sites do SourceForge. </para> + </example> + </listitem> + + <listitem> + <para>Como eu uso isso com <varname>PATCH<replaceable>*</replaceable></varname>?</para> + + <para>Todos os exemplos foram feitos com <varname>MASTER<replaceable>*</replaceable></varname> mas eles funcionam exatamente da mesma forma com <varname>PATCH<replaceable>*</replaceable></varname> como pode ser visto em <xref linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para> + + <example xml:id="ports-master-sites-n-example-detailed-use-patch-sites"> + + <title>Uso Simplificado de <literal>MASTER_SITES:n</literal> com <varname>PATCH_SITES</varname></title> + + <programlisting>PATCH_SITES= http://site1/ http://site2/:test +PATCHFILES= patch1:test</programlisting> + </example> + </listitem> + </orderedlist> + </sect3> + + <sect3 xml:id="port-master-sites-n-what-changed"> + <title>O que Muda para os Ports? O que Não Funciona?</title> + + <orderedlist numeration="lowerroman"> + <listitem> + <para>Todos os ports atuais permanecem os mesmos. A feature <literal>MASTER_SITES:n</literal> só é ativada se houver elementos pós-fixados com <literal>:<replaceable>n</replaceable></literal> como elementos de acordo com as regras de sintaxe acima, especialmente como mostrado no item <xref linkend="porting-master-sites-n-group-semantics"/>.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-what-changes-in-port-targets"> + <para>Os targets de port permanecem os mesmos: <buildtarget>checksum</buildtarget>, <buildtarget>makesum</buildtarget>, <buildtarget>patch</buildtarget>, <buildtarget>configure</buildtarget>, <buildtarget>build</buildtarget>, etc. Com as exceções óbvias de <buildtarget>do-fetch</buildtarget>, <buildtarget>fetch-list</buildtarget>, <buildtarget>master-sites</buildtarget> e <buildtarget>patch-sites</buildtarget>.</para> + + <itemizedlist> + <listitem> + <para><buildtarget>do-fetch</buildtarget>: implementa o novo agrupamento pós-fixado <varname>DISTFILES</varname> e <varname>PATCHFILES</varname> com seus elementos de grupo correspondentes dentro de ambos <varname>MASTER_SITES</varname> e <varname>PATCH_SITES</varname> que usam elementos de grupo correspondentes dentro de ambos <varname>MASTER_SITE_SUBDIR</varname> e <varname>PATCH_SITE_SUBDIR</varname>. Verifique <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + </listitem> + + <listitem> + <para><buildtarget>fetch-list</buildtarget>: funciona como o antigo <buildtarget>fetch-list</buildtarget>, com a exceção de que faz agrupamentos exatamente como o <buildtarget>do-fetch</buildtarget>.</para> + </listitem> + + <listitem> + <para><buildtarget>master-sites</buildtarget> e <buildtarget>patch-sites</buildtarget>: (incompatível com versões mais antigas) somente retorna os elementos do grupo <literal>DEFAULT</literal>; na verdade, eles executam os targets <buildtarget>master-sites-default</buildtarget> e <buildtarget>patch-sites-default</buildtarget> respectivamente.</para> + + <para>Além disso, usar o target <buildtarget>master-sites-all</buildtarget> ou <buildtarget>patch-sites-all</buildtarget> é o preferido para verificar diretamente <buildtarget>MASTER_SITES</buildtarget> ou <buildtarget>PATCH_SITES</buildtarget>. Além disso, não é garantido que a checagem direta funcione em versões futuras. Veja <xref linkend="porting-master-sites-n-new-port-targets-master-sites-all"/> para obter mais informações sobre esses novos tagets de port.</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>Novos Targets de Port</para> + + <orderedlist> + <listitem> + <para>Existem targets <buildtarget>master-sites-<replaceable>n</replaceable></buildtarget> e <buildtarget>patch-sites-<replaceable>n</replaceable></buildtarget> que listarão os elementos do respectivo grupo <replaceable>n</replaceable> dentro de <varname>MASTER_SITES</varname> e <varname>PATCH_SITES</varname> respectivamente. Por exemplo, ambos <buildtarget>master-sites-DEFAULT</buildtarget> e <buildtarget>patch-sites-DEFAULT</buildtarget> retornarão os elementos do grupo <literal>DEFAULT</literal>, <buildtarget>master-sites-test</buildtarget> e <buildtarget>patch-sites-test</buildtarget> do grupo <literal>test</literal>.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-new-port-targets-master-sites-all"> + <para>Há novos targets <buildtarget>master-sites-all</buildtarget> e <buildtarget>patch-sites-all</buildtarget> que fazem o trabalho dos antigos <buildtarget>master-sites</buildtarget> e <buildtarget>patch-sites</buildtarget>. Eles retornam os elementos de todos os grupos como se todos pertencessem ao mesmo grupo, com a ressalva de que lista tantos <varname>MASTER_SITE_BACKUP</varname> e <varname>MASTER_SITE_OVERRIDE</varname> como existem grupos definidos dentro de qualquer <varname>DISTFILES</varname> ou <varname>PATCHFILES</varname>; respectivamente para <buildtarget>master-sites-all</buildtarget> e <buildtarget>patch-sites-all</buildtarget>.</para> + </listitem> + </orderedlist> + </listitem> + </orderedlist> + </sect3> + </sect2> + + <sect2 xml:id="makefile-dist_subdir"> + <title><varname>DIST_SUBDIR</varname></title> + + <para>Não deixe o <filename>/usr/ports/distfiles</filename> bagunçado. Se um port exigir que muitos arquivos sejam baixados, ou que contenha um arquivo que tenha um nome que possa entrar em conflito com outros ports (por exemplo, <filename>Makefile</filename>), defina <varname>DIST_SUBDIR</varname> com o nome do port (<literal>${PORTNAME}</literal> ou <literal>${PKGNAMEPREFIX}${PORTNAME}</literal>). Isso vai mudar o <varname>DISTDIR</varname> do padrão <filename>/usr/ports/distfiles</filename> para <filename>/usr/ports/distfiles/${DIST_SUBDIR}</filename>,e assim, será colocado tudo o que é necessário para o port nesse subdiretório.</para> + + <para>Ele também examinará o subdiretório com o mesmo nome no site principal de backup em <link xlink:href="http://distcache.FreeBSD.org">http://distcache.FreeBSD.org</link> (Configurar o <varname>DISTDIR</varname> explicitamente no <filename>Makefile</filename> não fará isso funcionar, então por favor use <varname>DIST_SUBDIR</varname>.</para> + + <note> + <para>Isso não afeta o <varname>MASTER_SITES</varname> definido no <filename>Makefile</filename>.</para> + </note> + </sect2> + </sect1> + + <sect1 xml:id="makefile-maintainer"> + <title><varname>MAINTAINER</varname></title> + + <para>Defina seu endereço de email aqui. Por favor. <emphasis>:-)</emphasis></para> + + <para>Apenas um único endereço sem a parte de comentário é permitido como um valor para <varname>MAINTAINER</varname>. O formato usado é <literal>user@hostname.domain</literal>. Por favor, não inclua nenhum texto descritivo, como um nome nesta entrada. Isso confunde a infraestrutura do Ports e a maioria das ferramentas que a usam.</para> + + <para>O mantenedor é responsável por manter o port atualizado e garantir que elo funcione corretamente. Para obter uma descrição detalhada das responsabilidades de um mantenedor de port, consulte <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/contributing/ports-contributing.html#maintain-port">O desafio para os mantenedores de port</link>.</para> + + <note> + <para>Um mantenedor se voluntaria para manter um port em bom estado de funcionamento. Os mantenedores têm a responsabilidade primária por seus ports, mas não possuem propriedade exclusiva. Os ports existem para o benefício da comunidade e, na realidade, pertencem à comunidade. O que isso significa é que outras pessoas além do mantenedor, também podem fazer alterações em um port. Grandes mudanças na Coleção de Ports podem exigir mudanças em muitos ports. A Equipe de Gerenciamento do Ports do FreeBSD ou membros de outras equipes podem modificar ports para corrigir problemas de dependência ou outros problemas, como um bump de versão para uma atualização de biblioteca compartilhada.</para> + + <para>Alguns tipos de correções tem <quote>aprovação implícita</quote> da Equipe de Gerenciamento de Ports <email>portmgr@FreeBSD.org</email>, permitindo que qualquer committer conserte essas categorias de problemas em qualquer port. Essas correções não precisam de aprovação do mantenedor. A aprovação implícita não se aplica a ports que são mantidos por times como <email role="nolink">autotools@FreeBSD.org</email>, <email role="nolink">x11@FreeBSD.org</email>, <email role="nolink">gnome@FreeBSD.org</email> ou <email role="nolink">kde@FreeBSD.org</email>. Esses times usam repositórios externos e podem ter alterações que entrariam em conflito com mudanças que normalmente seriam abrangidas pela aprovação implícita.</para> + + <para>A aprovação implícita da maioria dos ports se aplica a esses tipos de correções:</para> + + <itemizedlist> + <listitem> + <para>A maioria das alterações de infraestrutura em um port (ou seja, modernizar, mas não alterar nenhuma funcionalidade). Por exemplo, converter para staging, ativar modo verboso nas compilações, <varname>USE_GMAKE</varname> para <literal>USES=gmake</literal>, o novo <varname>LIB_DEPENDS</varname> formato...</para> + </listitem> + + <listitem> + <para>Correções de compilação e de tempo de execução triviais e <emphasis>testadas</emphasis>.</para> + </listitem> + </itemizedlist> + </note> + + <para>Outras alterações no port serão enviadas ao mantenedor para revisão e aprovação antes de se fazer o commit. Se o mantenedor não responder a uma solicitação de atualização após duas semanas (excluindo os principais feriados), isso será considerado como timeout do mantenedor, e a atualização poderá ser feita sem a aprovação explícita do mesmo. Se o mantenedor não responder dentro de três meses, ou se houver três timeouts consecutivos, então o mantenedor é considerado ausente, e todas os seus ports podem ser atribuídos de volta para à comunidade. Exceções para isso são quaisquer ports mantidos pela Equipe de Gerenciamento de Ports <email>portmgr@FreeBSD.org</email> ou pela Equipe de Oficias de Segurança <email>security-officer@FreeBSD.org</email>. Nenhum commit não autorizado pode ser feito em ports mantidos por esses grupos.</para> + + <para>Reservamo-nos o direito de modificar as submissões do mantenedor para melhor adequar as políticas e os estilos existentes da Coleção de Ports sem aprovação explicita do remetente ou do mantenedor. Além disso, grandes alterações de infraestrutura podem resultar na modificação de um port sem o consentimento do mantenedor. Estes tipos de alterações nunca irão afetar a funcionalidade do port.</para> + + <para>A Equipe de Gerenciamento de Ports <email>portmgr@FreeBSD.org</email> reserva o direito de revogar ou substituir a propriedade de mantenedor de qualquer pessoa por qualquer motivo, e a Equipe de Oficiais de Segurança <email>security-officer@FreeBSD.org</email> reserva o direito de revogar ou substituir a propriedade de mantenedor por razões de segurança. </para> + </sect1> + + <sect1 xml:id="makefile-comment"> + <title><varname>COMMENT</varname></title> + + <para>O comentário é uma descrição de uma linha de um port mostrada por <command>pkg info</command>. Por favor, siga estas regras ao compor:</para> + + <orderedlist> + <listitem> + <para>A string COMMENT deve ter 70 caracteres ou menos.</para> + </listitem> + + <listitem> + <para><emphasis>Não</emphasis> inclua o nome do pacote ou o número da versão do software. </para> + </listitem> + + <listitem> + <para>O comentário deve começar com uma letra maiúscula e terminar sem um ponto final.</para> + </listitem> + + <listitem> + <para>Não comece com um artigo indefinido (isto é, A ou Um).</para> + </listitem> + + <listitem> + <para>Capitalize nomes como Apache, JavaScript ou Perl.</para> + </listitem> + + <listitem> + <para>Use uma vírgula serial para listas de palavras: "verde, vermelho<emphasis>,</emphasis> e azul."</para> + </listitem> + + <listitem> + <para>Verifique erros de ortografia.</para> + </listitem> + </orderedlist> + + <para>Aqui está um exemplo:</para> + + <programlisting>COMMENT= Cat chasing a mouse all over the screen</programlisting> + + <para>A variável COMMENT vem depois da variável MAINTAINER no <filename>Makefile</filename>.</para> + </sect1> + + <sect1 xml:id="licenses"> + <title>Licenças</title> + + <para>Cada port deve documentar a licença sob a qual está disponível. Se não for uma licença aprovada pelo OSI, também deve documentar quaisquer restrições à redistribuição.</para> + + <sect2 xml:id="licenses-license"> + <title><varname>LICENSE</varname></title> + + <para>Um nome abreviado para a licença ou licenças se mais de uma licença for aplicada.</para> + + <para>Se for uma das licenças listadas no <xref linkend="licenses-license-list"/>, apenas as variáveis <varname>LICENSE_FILE</varname> e <varname>LICENSE_DISTFILES</varname> podem ser definidas.</para> + + <para>Se esta for uma licença que não tenha sido definida na infraestrutura de ports (veja <xref linkend="licenses-license-list"/>), <varname>LICENSE_PERMS</varname> e <varname>LICENSE_NAME</varname> devem ser definidos, juntamente com <varname>LICENSE_FILE</varname> ou <varname>LICENSE_TEXT</varname>. <varname>LICENSE_DISTFILES</varname> e <varname>LICENSE_GROUPS</varname> também podem ser definidos, mas não é necessário.</para> + + <para>As licenças pré-definidas são mostradas em <xref linkend="licenses-license-list"/>. A lista atual está sempre disponível em <filename>Mk/bsd.licenses.db.mk</filename>.</para> + + <example xml:id="licenses-license-ex1"> + <title>Uso Mais Simples, Licenças Predefinidas</title> + + <para>Quando o <filename>README</filename> de algum software diz <quote>This software is under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.</quote> mas não fornece o arquivo de licença, use isto:</para> + + <programlisting>LICENSE= LGPL21+</programlisting> + + <para>Quando o software fornece o arquivo de licença, use isto:</para> + + <programlisting>LICENSE= LGPL21+ +LICENSE_FILE= ${WRKSRC}/COPYING</programlisting> + </example> + + <para>Para as licenças predefinidas, as permissões padrão são <literal>dist-mirror dist-sell pkg-mirror pkg-sell auto-accept</literal>.</para> + + <table frame="none" xml:id="licenses-license-list"> + <title>Lista de Licenças Predefinidas</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Nome Curto</entry> + <entry>Nome</entry> + <entry>Grupo</entry> + <entry>Permissões</entry> + </row> + </thead> + + <!-- + from any port, run + for i in $(make -V _LICENSE_LIST:O) + do + echo "<row xml:id=\"licenses-license-${i/+/_}\">" + echo "<entry><literal>$i</literal></entry>" + echo "<entry>$(make -V _LICENSE_NAME_$i)</entry>" + echo "<entry>$(make -V '${_LICENSE_GROUPS_'$i':@p@<literal>${p}</literal>@}')</entry>" + if [ "$(make -V _LICENSE_PERMS_DEFAULT)" = "$(make -V _LICENSE_PERMS_$i)" ] + then + echo "<entry>(default)</entry>" + else + echo "<entry>$(make -V '${_LICENSE_PERMS_'$i':@p@<literal>${p}</literal>@}')</entry>" + fi + echo "</row>" + echo + done + --> + <tbody> + <row xml:id="licenses-license-AGPLv3"> + <entry><literal>AGPLv3</literal></entry> + <entry>GNU Affero General Public License version 3</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-AGPLv3_"> + <entry><literal>AGPLv3+</literal></entry> + <entry>GNU Affero General Public License version 3 (ou maior)</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-APACHE10"> + <entry><literal>APACHE10</literal></entry> + <entry>Apache License 1.0</entry> + <entry><literal>FSF</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-APACHE11"> + <entry><literal>APACHE11</literal></entry> + <entry>Apache License 1.1</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-APACHE20"> + <entry><literal>APACHE20</literal></entry> + <entry>Apache License 2.0</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-ART10"> + <entry><literal>ART10</literal></entry> + <entry>Artistic License version 1.0</entry> + <entry><literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-ART20"> + <entry><literal>ART20</literal></entry> + <entry>Artistic License version 2.0</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-ARTPERL10"> + <entry><literal>ARTPERL10</literal></entry> + <entry>Artistic License (perl) version 1.0</entry> + <entry><literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-BSD"> + <entry><literal>BSD</literal></entry> + <entry>BSD license Generic Version (deprecated)</entry> + <entry><literal>FSF</literal> <literal>OSI</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-BSD2CLAUSE"> + <entry><literal>BSD2CLAUSE</literal></entry> + <entry>BSD 2-clause "Simplified" License</entry> + <entry><literal>FSF</literal> <literal>OSI</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-BSD3CLAUSE"> + <entry><literal>BSD3CLAUSE</literal></entry> + <entry>BSD 3-clause "New" or "Revised" License</entry> + <entry><literal>FSF</literal> <literal>OSI</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-BSD4CLAUSE"> + <entry><literal>BSD4CLAUSE</literal></entry> + <entry>BSD 4-clause "Original" or "Old" License</entry> + <entry><literal>FSF</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-BSL"> + <entry><literal>BSL</literal></entry> + <entry>Boost Software License</entry> + <entry><literal>FSF</literal> <literal>OSI</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-1.0"> + <entry><literal>CC-BY-1.0</literal></entry> + <entry>Creative Commons Attribution 1.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-2.0"> + <entry><literal>CC-BY-2.0</literal></entry> + <entry>Creative Commons Attribution 2.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-2.5"> + <entry><literal>CC-BY-2.5</literal></entry> + <entry>Creative Commons Attribution 2.5</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-3.0"> + <entry><literal>CC-BY-3.0</literal></entry> + <entry>Creative Commons Attribution 3.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-4.0"> + <entry><literal>CC-BY-4.0</literal></entry> + <entry>Creative Commons Attribution 4.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-1.0"> + <entry><literal>CC-BY-NC-1.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial 1.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-2.0"> + <entry><literal>CC-BY-NC-2.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial 2.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-2.5"> + <entry><literal>CC-BY-NC-2.5</literal></entry> + <entry>Creative Commons Attribution Non Commercial 2.5</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-3.0"> + <entry><literal>CC-BY-NC-3.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial 3.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-4.0"> + <entry><literal>CC-BY-NC-4.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial 4.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-ND-1.0"> + <entry><literal>CC-BY-NC-ND-1.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial No Derivatives 1.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-ND-2.0"> + <entry><literal>CC-BY-NC-ND-2.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial No Derivatives 2.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-ND-2.5"> + <entry><literal>CC-BY-NC-ND-2.5</literal></entry> + <entry>Creative Commons Attribution Non Commercial No Derivatives 2.5</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-ND-3.0"> + <entry><literal>CC-BY-NC-ND-3.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial No Derivatives 3.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-ND-4.0"> + <entry><literal>CC-BY-NC-ND-4.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial No Derivatives 4.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-SA-1.0"> + <entry><literal>CC-BY-NC-SA-1.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial Share Alike 1.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-SA-2.0"> + <entry><literal>CC-BY-NC-SA-2.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial Share Alike 2.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-SA-2.5"> + <entry><literal>CC-BY-NC-SA-2.5</literal></entry> + <entry>Creative Commons Attribution Non Commercial Share Alike 2.5</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-SA-3.0"> + <entry><literal>CC-BY-NC-SA-3.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial Share Alike 3.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-NC-SA-4.0"> + <entry><literal>CC-BY-NC-SA-4.0</literal></entry> + <entry>Creative Commons Attribution Non Commercial Share Alike 4.0</entry> + <entry/> + <entry><literal>dist-mirror</literal> <literal>pkg-mirror</literal> <literal>auto-accept</literal></entry> + </row> + + <row xml:id="licenses-license-CC-BY-ND-1.0"> + <entry><literal>CC-BY-ND-1.0</literal></entry> + <entry>Creative Commons Attribution No Derivatives 1.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-ND-2.0"> + <entry><literal>CC-BY-ND-2.0</literal></entry> + <entry>Creative Commons Attribution No Derivatives 2.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-ND-2.5"> + <entry><literal>CC-BY-ND-2.5</literal></entry> + <entry>Creative Commons Attribution No Derivatives 2.5</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-ND-3.0"> + <entry><literal>CC-BY-ND-3.0</literal></entry> + <entry>Creative Commons Attribution No Derivatives 3.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-ND-4.0"> + <entry><literal>CC-BY-ND-4.0</literal></entry> + <entry>Creative Commons Attribution No Derivatives 4.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-SA-1.0"> + <entry><literal>CC-BY-SA-1.0</literal></entry> + <entry>Creative Commons Attribution Share Alike 1.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-SA-2.0"> + <entry><literal>CC-BY-SA-2.0</literal></entry> + <entry>Creative Commons Attribution Compartilhar Alike 2.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-SA-2.5"> + <entry><literal>CC-BY-SA-2.5</literal></entry> + <entry>Creative Commons Attribution Share Alike 2.5</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-SA-3.0"> + <entry><literal>CC-BY-SA-3.0</literal></entry> + <entry>Creative Commons Attribution Share Alike 3.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC-BY-SA-4.0"> + <entry><literal>CC-BY-SA-4.0</literal></entry> + <entry>Creative Commons Attribution Share Alike 4.0</entry> + <entry/> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CC0-1.0"> + <entry><literal>CC0-1.0</literal></entry> + <entry>Creative Commons Zero v1.0 Universal</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CDDL"> + <entry><literal>CDDL</literal></entry> + <entry>Common Development and Distribution License</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-CPAL-1.0"> + <entry><literal>CPAL-1.0</literal></entry> + <entry>Common Public Attribution License</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-ClArtistic"> + <entry><literal>ClArtistic</literal></entry> + <entry>Clarified Artistic License</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-EPL"> + <entry><literal>EPL</literal></entry> + <entry>Eclipse Public License</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GFDL"> + <entry><literal>GFDL</literal></entry> + <entry>GNU Free Documentation License</entry> + <entry><literal>FSF</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GMGPL"> + <entry><literal>GMGPL</literal></entry> + <entry>GNAT Modified General Public License</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GPLv1"> + <entry><literal>GPLv1</literal></entry> + <entry>GNU General Public License version 1</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GPLv1_"> + <entry><literal>GPLv1+</literal></entry> + <entry>GNU General Public License version 1 (or later)</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GPLv2"> + <entry><literal>GPLv2</literal></entry> + <entry>GNU General Public License version 2</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GPLv2_"> + <entry><literal>GPLv2+</literal></entry> + <entry>GNU General Public License version 2 (or later)</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GPLv3"> + <entry><literal>GPLv3</literal></entry> + <entry>GNU General Public License version 3</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GPLv3_"> + <entry><literal>GPLv3+</literal></entry> + <entry>GNU General Public License version 3 (or later)</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GPLv3RLE"> + <entry><literal>GPLv3RLE</literal></entry> + <entry>GNU GPL version 3 Runtime Library Exception</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-GPLv3RLE_"> + <entry><literal>GPLv3RLE+</literal></entry> + <entry>GNU GPL version 3 Runtime Library Exception (or later)</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-ISCL"> + <entry><literal>ISCL</literal></entry> + <entry>Internet Systems Consortium License</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-LGPL20"> + <entry><literal>LGPL20</literal></entry> + <entry>GNU Library General Public License version 2.0</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-LGPL20_"> + <entry><literal>LGPL20+</literal></entry> + <entry>GNU Library General Public License version 2.0 (or later)</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-LGPL21"> + <entry><literal>LGPL21</literal></entry> + <entry>GNU Lesser General Public License version 2.1</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-LGPL21_"> + <entry><literal>LGPL21+</literal></entry> + <entry>GNU Lesser General Public License version 2.1 (or later)</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-LGPL3"> + <entry><literal>LGPL3</literal></entry> + <entry>GNU Lesser General Public License version 3</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-LGPL3_"> + <entry><literal>LGPL3+</literal></entry> + <entry>GNU Lesser General Public License version 3 (or later)</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-LPPL10"> + <entry><literal>LPPL10</literal></entry> + <entry>LaTeX Project Public License version 1.0</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry><literal>dist-mirror</literal> <literal>dist-sell</literal></entry> + </row> + + <row xml:id="licenses-license-LPPL11"> + <entry><literal>LPPL11</literal></entry> + <entry>LaTeX Project Public License version 1.1</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry><literal>dist-mirror</literal> <literal>dist-sell</literal></entry> + </row> + + <row xml:id="licenses-license-LPPL12"> + <entry><literal>LPPL12</literal></entry> + <entry>LaTeX Project Public License version 1.2</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry><literal>dist-mirror</literal> <literal>dist-sell</literal></entry> + </row> + + <row xml:id="licenses-license-LPPL13"> + <entry><literal>LPPL13</literal></entry> + <entry>LaTeX Project Public License version 1.3</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry><literal>dist-mirror</literal> <literal>dist-sell</literal></entry> + </row> + + <row xml:id="licenses-license-LPPL13a"> + <entry><literal>LPPL13a</literal></entry> + <entry>LaTeX Project Public License version 1.3a</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry><literal>dist-mirror</literal> <literal>dist-sell</literal></entry> + </row> + + <row xml:id="licenses-license-LPPL13b"> + <entry><literal>LPPL13b</literal></entry> + <entry>LaTeX Project Public License version 1.3b</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry><literal>dist-mirror</literal> <literal>dist-sell</literal></entry> + </row> + + <row xml:id="licenses-license-LPPL13c"> + <entry><literal>LPPL13c</literal></entry> + <entry>LaTeX Project Public License version 1.3c</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry><literal>dist-mirror</literal> <literal>dist-sell</literal></entry> + </row> + + <row xml:id="licenses-license-MIT"> + <entry><literal>MIT</literal></entry> + <entry>MIT license / X11 license</entry> + <entry><literal>COPYFREE</literal> <literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-MPL10"> + <entry><literal>MPL10</literal></entry> + <entry>Mozilla Public License version 1.0</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-MPL11"> + <entry><literal>MPL11</literal></entry> + <entry>Mozilla Public License version 1.1</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-MPL20"> + <entry><literal>MPL20</literal></entry> + <entry>Mozilla Public License version 2.0</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-NCSA"> + <entry><literal>NCSA</literal></entry> + <entry>University of Illinois/NCSA Open Source License</entry> + <entry><literal>COPYFREE</literal> <literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-NONE"> + <entry><literal>NONE</literal></entry> + <entry>No license specified</entry> + <entry/> + <entry><literal>none</literal></entry> + </row> + + <row xml:id="licenses-license-OFL10"> + <entry><literal>OFL10</literal></entry> + <entry>SIL Open Font License version 1.0 (http://scripts.sil.org/OFL)</entry> + <entry><literal>FONTS</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-OFL11"> + <entry><literal>OFL11</literal></entry> + <entry>SIL Open Font License version 1.1 (http://scripts.sil.org/OFL)</entry> + <entry><literal>FONTS</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-OWL"> + <entry><literal>OWL</literal></entry> + <entry>Open Works License (owl.apotheon.org)</entry> + <entry><literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-OpenSSL"> + <entry><literal>OpenSSL</literal></entry> + <entry>Licença OpenSSL</entry> + <entry><literal>FSF</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-PD"> + <entry><literal>PD</literal></entry> + <entry>Public Domain</entry> + <entry><literal>GPL</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-PHP202"> + <entry><literal>PHP202</literal></entry> + <entry>PHP License version 2.02</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-PHP30"> + <entry><literal>PHP30</literal></entry> + <entry>PHP License version 3.0</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-PHP301"> + <entry><literal>PHP301</literal></entry> + <entry>PHP License versão 3.01</entry> + <entry><literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-PSFL"> + <entry><literal>PSFL</literal></entry> + <entry>Python Software Foundation License</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-PostgreSQL"> + <entry><literal>PostgreSQL</literal></entry> + <entry>PostgreSQL Licence</entry> + <entry><literal>FSF</literal> <literal>GPL</literal> <literal>OSI</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-RUBY"> + <entry><literal>RUBY</literal></entry> + <entry>Ruby License</entry> + <entry><literal>FSF</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-UNLICENSE"> + <entry><literal>UNLICENSE</literal></entry> + <entry>The Unlicense</entry> + <entry><literal>COPYFREE</literal> <literal>FSF</literal> <literal>GPL</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-WTFPL"> + <entry><literal>WTFPL</literal></entry> + <entry>Do What the Fuck You Want To Public License version 2</entry> + <entry><literal>GPL</literal> <literal>FSF</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-WTFPL1"> + <entry><literal>WTFPL1</literal></entry> + <entry>Do What the Fuck You Want To Public License version 1</entry> + <entry><literal>GPL</literal> <literal>FSF</literal> <literal>COPYFREE</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-ZLIB"> + <entry><literal>ZLIB</literal></entry> + <entry>zlib License</entry> + <entry><literal>GPL</literal> <literal>FSF</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + + <row xml:id="licenses-license-ZPL21"> + <entry><literal>ZPL21</literal></entry> + <entry>Zope Public License version 2.1</entry> + <entry><literal>GPL</literal> <literal>OSI</literal></entry> + <entry>(padrão)</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2 xml:id="licenses-license_perms"> + <title><varname>LICENSE_PERMS</varname> e <varname>LICENSE_PERMS_<replaceable>NAME</replaceable></varname></title> + + <para>Permissões. Use <literal>none</literal> se vazio.</para> + + <variablelist xml:id="licenses-license_perms-list"> + <title>Lista de Permissões de Licença</title> + + <varlistentry xml:id="licenses-license_perms-dist-mirror"> + <term><literal>dist-mirror</literal></term> + + <listitem> + <para>A redistribuição dos arquivos de distribuição é permitida. Os arquivos de distribuição serão adicionados ao FreeBSD <acronym>CDN</acronym> <varname>MASTER_SITE_BACKUP</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-no-dist-mirror"> + <term><literal>no-dist-mirror</literal></term> + + <listitem> + <para>A redistribuição dos arquivos de distribuição é proibida. Isso é equivalente a <link linkend="porting-restrictions-restricted"><varname>RESTRICT</varname></link>. Os arquivos de distribuição <emphasis>não</emphasis> serão adicionados ao FreeBSD <acronym>CDN</acronym> <varname>MASTER_SITE_BACKUP</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-dist-sell"> + <term><literal>dist-sell</literal></term> + + <listitem> + <para>A venda de arquivos de distribuição é permitida. Os arquivos de distribuição estarão presentes nas imagens do instalador.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-no-dist-sell"> + <term><literal>no-dist-sell</literal></term> + + <listitem> + <para>A venda de arquivos de distribuição é proibida. Isso é equivalente a <link linkend="porting-restrictions-no_cdrom"><varname>NO_CDROM</varname></link>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-pkg-mirror"> + <term><literal>pkg-mirror</literal></term> + + <listitem> + <para>É permitida a redistribuição gratuita do pacote. O pacote será distribuído na <acronym>CDN</acronym> de pacotes do FreeBSD <link xlink:href="https://pkg.freebsd.org/">https://pkg.freebsd.org/</link>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-no-pkg-mirror"> + <term><literal>no-pkg-mirror</literal></term> + + <listitem> + <para>É proibida a redistribuição gratuita do pacote. Equivalente à definir <link linkend="porting-restrictions-no_package"><varname>NO_PACKAGE</varname></link>. O pacote <emphasis>não</emphasis> será distribuído a partir da <acronym>CDN</acronym> de pacotes do FreeBSD <link xlink:href="https://pkg.freebsd.org/">https://pkg.freebsd.org/</link>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-pkg-sell"> + <term><literal>pkg-sell</literal></term> + + <listitem> + <para>A venda do pacote é permitida. O pacote estará presente nas imagens do instalador.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-no-pkg-sell"> + <term><literal>no-pkg-sell</literal></term> + + <listitem> + <para>A venda de pacotes é proibida. Isso é equivalente a definir <link linkend="porting-restrictions-no_cdrom"><varname>NO_CDROM</varname></link>. O pacote <emphasis>não</emphasis> estará presente nas imagens do instalador. </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-auto-accept"> + <term><literal>auto-accept</literal></term> + + <listitem> + <para>A licença é aceita por padrão. Os prompts para aceitar uma licença não são exibidos a menos que o usuário tenha definido <varname>LICENSES_ASK</varname>. Use isto, a menos que a licença indique que o usuário deve aceitar os termos da licença. </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_perms-no-auto-accept"> + <term><literal>no-auto-accept</literal></term> + + <listitem> + <para>A licença não é aceita por padrão. O usuário sempre será solicitado a confirmar a aceitação desta licença. Isso deve ser usado se a licença declarar que o usuário deve aceitar seus termos.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Quando ambos <literal><replaceable>permission</replaceable></literal> e <literal>no-<replaceable>permission</replaceable> </literal> estiverem presentes o <literal>no-<replaceable>permission</replaceable></literal> vai cancelar a <literal><replaceable>permission</replaceable></literal>.</para> + + <para>Quando <literal><replaceable>permission</replaceable></literal> não estiver presente, é considerado uma <literal>no-<replaceable>permission</replaceable></literal>.</para> + + <example xml:id="licenses-license_perms-ex1"> + <title>Licença Não Padrão</title> + + <para>Leia os termos da licença e traduza-os usando as permissões disponíveis.</para> + + <programlisting>LICENSE= UNKNOWN +LICENSE_NAME= unknown +LICENSE_TEXT= Esse programa NÃO é de domínio publico.\ + pode ser distribuído livremente para propósitos não comerciais apenas,\ + e NÃO HÁ GARANTIA PARA ESSE PROGRAMA. +LICENSE_PERMS= dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept</programlisting> + </example> + + <example xml:id="licenses-license_perms-ex2"> + <title>Licenças Padrão e Não Padrão</title> + + <para>Leia os termos da licença e expresse-os usando as permissões disponíveis. Em caso de dúvida, peça orientação na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">lista de discussão de ports do FreeBSD</link>.</para> + + <programlisting>LICENSE= WARSOW GPLv2 +LICENSE_COMB= multi +LICENSE_NAME_WARSOW= Warsow Content License +LICENSE_FILE_WARSOW= ${WRKSRC}/docs/license.txt +LICENSE_PERMS_WARSOW= dist-mirror pkg-mirror auto-accept</programlisting> + + <para>Quando as permissões das licenças GPLv2 e UNKNOWN são misturadas, o port termina com <literal>dist-mirror dist-sell pkg-mirror pkg-sell auto-accept dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept</literal>. O <literal>no-<replaceable>permissions</replaceable></literal> cancela as <replaceable>permissions</replaceable>. A lista resultante de permissões é <replaceable>dist-mirror pkg-mirror auto-accept</replaceable>. Os arquivos de distribuição e os pacotes não estarão disponíveis nas imagens do instalador. </para> + </example> + </sect2> + + <sect2 xml:id="licenses-license_groups"> + <title><varname>LICENSE_GROUPS</varname> e <varname>LICENSE_GROUPS_<replaceable>NAME</replaceable></varname></title> + + <para>Grupos que a licença pertence.</para> + + <variablelist xml:id="licenses-license_groups-list"> + <title>Lista de Grupos de Licenças Predefinidas</title> + + <varlistentry xml:id="licenses-license_groups-FSF"> + <term><literal>FSF</literal></term> + + <listitem> + <para>Aprovada pela Free Software Foundation, veja <link xlink:href="http://www.fsf.org/licensing">FSF Licensing & Compliance Team</link>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_groups-GPL"> + <term><literal>GPL</literal></term> + + <listitem> + <para>Compatível com GPL</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_groups-OSI"> + <term><literal>OSI</literal></term> + + <listitem> + <para>Aprovado pelo OSI, veja a pagina Open Source Initiative <link xlink:href="http://opensource.org/licenses">Open Source Licenses</link>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_groups-COPYFREE"> + <term><literal>COPYFREE</literal></term> + + <listitem> + <para>Segue a Copyfree Standard Definition, consulte a pagina <link xlink:href="http://copyfree.org/standard/licenses">Copyfree Licenses</link>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="licenses-license_groups-FONTS"> + <term><literal>FONTS</literal></term> + + <listitem> + <para>Licenças de fonte</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 xml:id="licenses-license_name"> + <title><varname>LICENSE_NAME</varname> e <varname>LICENSE_NAME_<replaceable>NAME</replaceable></varname></title> + + <para>Nome completo da licença.</para> + + <example xml:id="licenses-license_name-ex1"> + <title><varname>LICENSE_NAME</varname></title> + + <programlisting>LICENSE= UNRAR +LICENSE_NAME= UnRAR License +LICENSE_FILE= ${WRKSRC}/license.txt +LICENSE_PERMS= dist-mirror dist-sell pkg-mirror pkg-sell auto-accept</programlisting> + </example> + </sect2> + + <sect2 xml:id="licenses-license_file"> + <title><varname>LICENSE_FILE</varname> e <varname>LICENSE_FILE_<replaceable>NOME</replaceable></varname></title> + + <para>Caminho completo para o arquivo que contém o texto da licença, geralmente <filename>${WRKSRC}/some/file</filename>. Se o arquivo não estiver no distfile e seu conteúdo for muito longo para ser colocado em <link linkend="licenses-license_text"><varname>LICENSE_TEXT</varname></link>, insira o texto em um novo arquivo em <filename>${FILESDIR}</filename>.</para> + + <example xml:id="licenses-license_file-ex1"> + <title><varname>LICENSE_FILE</varname></title> + + <programlisting>LICENSE= GPLv3+ +LICENSE_FILE= ${WRKSRC}/COPYING</programlisting> + </example> + </sect2> + + <sect2 xml:id="licenses-license_text"> + <title><varname>LICENSE_TEXT</varname> e <varname>LICENSE_TEXT_<replaceable>NAME</replaceable></varname></title> + + <para>Texto para usar como uma licença. Útil quando a licença não está nos arquivos de distribuição e seu texto é curto.</para> + + <example xml:id="licenses-license_text-ex1"> + <title><varname>LICENSE_TEXT</varname></title> + + <programlisting>LICENSE= UNKNOWN +LICENSE_NAME= unknown +LICENSE_TEXT= This program is NOT in public domain.\ + It can be freely distributed for non-commercial purposes only,\ + and THERE IS NO WARRANTY FOR THIS PROGRAM. +LICENSE_PERMS= dist-mirror no-dist-sell pkg-mirror no-pkg-sell auto-accept</programlisting> + </example> + </sect2> + + <sect2 xml:id="licenses-license_distfiles"> + <title><varname>LICENSE_DISTFILES</varname> e <varname>LICENSE_DISTFILES_<replaceable>NAME</replaceable></varname></title> + + <para>Os arquivos de distribuição aos quais as licenças se aplicam. O padrão é para todos os arquivos de distribuição.</para> + + <example xml:id="licenses-license_distfiles-ex1"> + <title><varname>LICENSE_DISTFILES</varname></title> + + <para>Usado quando os arquivos de distribuição não possuem a mesma licença. Por exemplo, um possui uma licença de código e outro possui alguns trabalhos de arte que não podem ser redistribuídos:</para> + + <programlisting>MASTER_SITES= SF/some-game +DISTFILES= ${DISTNAME}${EXTRACT_SUFX} artwork.zip + +LICENSE= BSD3CLAUSE ARTWORK +LICENSE_COMB= dual +LICENSE_NAME_ARTWORK= The game artwork license +LICENSE_TEXT_ARTWORK= The README says that the files cannot be redistributed +LICENSE_PERMS_ARTWORK= pkg-mirror pkg-sell auto-accept +LICENSE_DISTFILES_BSD3CLAUSE= ${DISTNAME}${EXTRACT_SUFX} +LICENSE_DISTFILES_ARTWORK= artwork.zip</programlisting> + </example> + </sect2> + + <sect2 xml:id="licenses-license_comb"> + <title><varname>LICENSE_COMB</varname></title> + + <para>Defina como <literal>multi</literal> se todas as licenças se aplicarem. Defina como <literal>dual</literal> se qualquer uma das licenças se aplica. O padrão é definido para <literal>single</literal>.</para> + + <example xml:id="licenses-license_comb-ex1"> + <title>Licenças Duplas</title> + + <para>Quando um port diz <quote>This software may be distributed under the GNU General Public License or the Artistic License</quote>>, isso significa que qualquer licença pode ser usada. Use isto:</para> + + <programlisting>LICENSE= ART10 GPLv1 +LICENSE_COMB= dual</programlisting> + + <para>Se os arquivos de licença forem fornecidos, use assim:</para> + + <programlisting>LICENSE= ART10 GPLv1 +LICENSE_COMB= dual +LICENSE_FILE_ART10= ${WRKSRC}/Artistic +LICENSE_FILE_GPLv1= ${WRKSRC}/Copying</programlisting> + </example> + + <example xml:id="licenses-license_comb-ex2"> + <title>Múltiplas Licenças</title> + + <para>Quando parte de um port tem uma licença, e outra parte tem uma licença diferente, use <literal>multi</literal>: </para> + + <programlisting>LICENSE= GPLv2 LGPL21+ +LICENSE_COMB= multi</programlisting> + </example> + + </sect2> + </sect1> + + <sect1 xml:id="makefile-portscout"> + <title><varname>PORTSCOUT</varname></title> + + <para><application>Portscout</application> é um utilitário de verificação de distfile automatizado para a Coleção de Ports do FreeBSD, descrito em detalhes em <xref linkend="distfile-survey"/>.</para> + + <para><varname>PORTSCOUT</varname> define condições especiais dentro das quais o scanner distfile do <application>Portscout</application> é restrito.</para> + + <para>Situações em que o <varname>PORTSCOUT</varname> é configurado: </para> + + <itemizedlist> + <listitem> + <para>Quando distfiles precisam ser ignorados, seja para versões específicas, ou para pequenas revisões específicas. Por exemplo, para excluir a versão <replaceable>8.2</replaceable> das verificações de versão de distfile porque é conhecido por estar quebrado, adicione:</para> + + <programlisting>PORTSCOUT= ignore:8.2</programlisting> + </listitem> + + <listitem> + <para>Quando versões específicas ou revisões maiores e menores específicas de um distfile devem ser verificadas. Por exemplo, se somente a versão <replaceable>0.6.4</replaceable> deve ser monitorado porque versões mais recentes têm problemas de compatibilidade com o FreeBSD, adicione: </para> + + <programlisting>PORTSCOUT= limit:^0\.6\.4</programlisting> + </listitem> + + <listitem> + <para>Quando os URLs que listam as versões disponíveis diferem dos URLs de download. Por exemplo, para limitar as verificações de versão do arquivo distfile à página de download para o port <package role="port">databases/pgtune</package>, adicione: </para> + + <programlisting>PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416</programlisting> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="makefile-depend"> + <title>Dependências</title> + + <para>Muitos ports dependem de outros ports. Esta é uma característica muito conveniente da maioria dos sistemas operacionais Unix-like, incluindo FreeBSD. Vários ports podem compartilhar uma dependência comum, ao invés de agrupar essa dependência com cada port ou pacote que precisa dela. Há sete variáveis que podem ser usadas para garantir que todos os bits necessários estejam na máquina do usuário. Existem também algumas variáveis de dependência pré-suportadas para casos comuns, além de algumas outras para controlar o comportamento das dependências.</para> + + <sect2 xml:id="makefile-lib_depends"> + <title><varname>LIB_DEPENDS</varname></title> + + <para>Esta variável especifica as bibliotecas compartilhadas das quais este port depende. É uma lista de tuplas <replaceable>lib</replaceable>:<replaceable>dir</replaceable> onde <replaceable>lib</replaceable> é o nome da biblioteca compartilhada, <replaceable>dir</replaceable> é o diretório no qual encontrá-lo, caso não esteja disponível. Por exemplo,</para> + + <programlisting>LIB_DEPENDS= libjpeg.so:graphics/jpeg</programlisting> + + <para>irá verificar se há uma biblioteca jpeg compartilhada com qualquer versão no subdiretório <filename>graphics/jpeg</filename> da árvore de ports para compilar e instalar se não for encontrado.</para> + + <para>A dependência é verificada duas vezes, uma vez dentro do target <buildtarget>build</buildtarget> e depois dentro do target <buildtarget>install</buildtarget>. Além disso, o nome da dependência é colocado no pacote para que o <command>pkg-install</command> (veja <citerefentry><refentrytitle>pkg-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>) a instale automaticamente se a mesma não estiver no sistema do usuário. </para> + </sect2> + + <sect2 xml:id="makefile-run_depends"> + <title><varname>RUN_DEPENDS</varname></title> + + <para>Esta variável especifica arquivos executáveis ou arquivos para os quais este port depende durante o tempo de execução. É uma lista de tuplas <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional> onde <replaceable>path</replaceable> é o nome do executável ou arquivo,<replaceable>dir</replaceable> é o diretório no qual encontrá-lo, caso não esteja disponível, e o <replaceable>target</replaceable> é o target para chamar nesse diretório. E se o <replaceable>path</replaceable> começar com uma barra (<literal>/</literal>), ele será tratado como um arquivo e sua existência é testada com <command>test -e</command>; caso contrário, é assumido como um executável e <command>which -s</command> é usado para determinar se o programa existe no caminho de pesquisa. </para> + + <para>Por exemplo,</para> + + <programlisting>RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:news/inn \ + xmlcatmgr:textproc/xmlcatmgr</programlisting> + + <para>irá verificar se o arquivo ou diretório <filename>/usr/local/news/bin/innd</filename> existe, e compilar e instalá-lo a partir do subdiretório <filename>news/inn</filename> da árvore de ports, caso não seja encontrado. Ele também verá se um executável chamado <command>xmlcatmgr</command> está no caminho de pesquisa em <filename>textproc/xmlcatmgr</filename> para compilar e instalar se não for encontrado. </para> + + <note> + <para>Nesse caso, <command>innd</command> é na verdade um executável; se um executável estiver em um local que não deve estar no caminho de pesquisa, use o nome do caminho completo.</para> + </note> + + <note> + <para>A pesquisa oficial <envar>PATH</envar> usado no cluster de construção de ports é </para> + + <programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin</programlisting> + </note> + + <para>A dependência é verificada a partir do target <buildtarget>install</buildtarget>. Além disso, o nome da dependência é colocado no pacote para que o <command>pkg-install</command> (veja <citerefentry><refentrytitle>pkg-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>) a instale automaticamente se a mesma não estiver no sistema do usuário. A parte <replaceable>target</replaceable> pode ser omitida se for igual a <varname>DEPENDS_TARGET</varname>.</para> + + <para>Uma situação bastante comum é quando <varname>RUN_DEPENDS</varname> é literalmente o mesmo que <varname>BUILD_DEPENDS</varname>, especialmente se o software portado é escrito em uma linguagem de script ou se requer o mesmo ambiente de compilação e tempo de execução. Neste caso, é tentador e intuitivo atribuir diretamente um ao outro: </para> + + <programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting> + + <para>No entanto, essa atribuição pode poluir as dependências de tempo de execução com entradas não definidas no <varname>BUILD_DEPENDS</varname> original do port. Isso acontece por causa de uma avaliação preguiçosa de atribuição de variáveis do <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Considere um <filename>Makefile</filename> com <varname>USES_<replaceable>*</replaceable></varname>, que são processados por <filename>ports/Mk/bsd.*.mk</filename> para aumentar as dependências iniciais de compilação. Por exemplo, <literal>USES=gmake</literal> adiciona <package role="port">devel/gmake</package> para <varname>BUILD_DEPENDS</varname>. Para evitar que essas dependências adicionais poluam <varname>RUN_DEPENDS</varname>, crie outra variável com o conteúdo atual de <varname>BUILD_DEPENDS</varname> e atribua-a para ambos <varname>BUILD_DEPENDS</varname> e <varname>RUN_DEPENDS</varname>:</para> + + <programlisting>MY_DEPENDS= some:devel/some \ + other:lang/other +BUILD_DEPENDS= ${MY_DEPENDS} +RUN_DEPENDS= ${MY_DEPENDS}</programlisting> + + <important> + <para><emphasis>Não</emphasis> use <literal>:=</literal> para atribuir <varname>BUILD_DEPENDS</varname> para <varname>RUN_DEPENDS</varname> ou vice-versa. Todas as variáveis são expandidas imediatamente, o que é exatamente a coisa errada a fazer e quase sempre um fracasso.</para> + </important> + </sect2> + + <sect2 xml:id="makefile-build_depends"> + <title><varname>BUILD_DEPENDS</varname></title> + + <para>Esta variável especifica executáveis ou arquivos que este port requer para ser compilado. Como <varname>RUN_DEPENDS</varname>, ela é uma lista de tuplas <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>. Por exemplo,</para> + + <programlisting>BUILD_DEPENDS= unzip:archivers/unzip</programlisting> + + <para>irá procurar por um executável chamado <command>unzip</command>, e ir para o subdiretório <filename>archivers/unzip</filename> da árvore de ports para compilar e instalar se não for encontrado.</para> + + <note> + <para><quote>build</quote> aqui significa tudo, desde a extração até a compilação. A dependência é verificada a partir do target <buildtarget>extract</buildtarget>. A parte do <replaceable>target</replaceable> pode ser omitida se for igual a <varname>DEPENDS_TARGET</varname></para> + </note> + </sect2> + + <sect2 xml:id="makefile-fetch_depends"> + <title><varname>FETCH_DEPENDS</varname></title> + + <para>Esta variável especifica executáveis ou arquivos que este port requer para fazer os downloads. Como os dois anteriores, é uma lista de tuplas <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>. Por exemplo,</para> + + <programlisting>FETCH_DEPENDS= ncftp2:net/ncftp2</programlisting> + + <para>irá procurar por um executável chamado <command>ncftp2</command> e ir para o subdiretório <filename>net/ncftp2</filename> da árvore de ports para compilar e instalar se não for encontrado. </para> + + <para>A dependência é verificada a partir do target <buildtarget>fetch</buildtarget>. A parte <replaceable>target</replaceable> pode ser omitida se for igual a <varname>DEPENDS_TARGET</varname>.</para> + </sect2> + + <sect2 xml:id="makefile-extract_depends"> + <title><varname>EXTRACT_DEPENDS</varname></title> + + <para>Esta variável especifica executáveis ou arquivos que este port requer para extração. Como no anterior, é uma lista de tuplas <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>. Por exemplo,</para> + + <programlisting>EXTRACT_DEPENDS= unzip:archivers/unzip</programlisting> + + <para>irá procurar por um executável chamado <command>unzip</command>, e ir para o subdiretório <filename>archivers/unzip</filename> da árvore de ports para compilar e instalar se não for encontrado.</para> + + <para>A dependência é verificada a partir do target <buildtarget>extract</buildtarget>. A parte <replaceable>target</replaceable> pode ser omitida se for igual a <varname>DEPENDS_TARGET</varname>.</para> + + <note> + <para>Use esta variável somente se a extração ainda não funcionar (o padrão usa <command>tar</command>) e não funciona com <literal>USES=tar</literal>, <literal>USES=lha</literal> ou <literal>USES=zip</literal> descrito em <xref linkend="uses"/>.</para> + </note> + </sect2> + + <sect2 xml:id="makefile-patch_depends"> + <title><varname>PATCH_DEPENDS</varname></title> + + <para>Esta variável especifica executáveis ou arquivos que este port requer para aplicar patches. Como no anterior, é uma lista de <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>. Por exemplo,</para> + + <programlisting>PATCH_DEPENDS= ${NONEXISTENT}:java/jfc:extract</programlisting> + + <para>vai descer para o subdiretório <filename>java/jfc</filename> da árvore de ports para extraí-lo. </para> + + <para>A dependência é verificada a partir do target <buildtarget>patch</buildtarget>. A parte <replaceable>target</replaceable> pode ser omitida se for igual a <varname>DEPENDS_TARGET</varname>.</para> + </sect2> + + <sect2 xml:id="makefile-uses"> + <title><varname>USES</varname></title> + + <para>Parâmetros podem ser adicionados para definir diferentes recursos e dependências usados pelo port. Eles são especificados adicionando esta linha ao <filename>Makefile</filename>:</para> + + <programlisting>USES= feature[:arguments]</programlisting> + + <para>Para a lista completa de valores, por favor veja o <xref linkend="uses"/>.</para> + + <warning> + <para><varname>USES</varname> não pode ser atribuído após a inclusão de <filename>bsd.port.pre.mk</filename>.</para> + </warning> + </sect2> + + <sect2 xml:id="makefile-use-vars"> + <title><varname>USE_<replaceable>*</replaceable></varname></title> + + <para>Diversas variáveis existem para definir dependências comuns compartilhadas por muitos ports. O uso é opcional, mas ajuda a reduzir a verbosidade dos <filename>Makefile</filename>s de port . Cada um deles é denominado como <varname>USES_<replaceable>*</replaceable></varname>. Essas variáveis podem ser usadas apenas no <filename>Makefile</filename> do port e <filename>ports/Mk/bsd.*.mk</filename>. Elas não são destinadas a opções configuráveis pelo usuário - use <varname>PORT_OPTIONS</varname> para esse propósito.</para> + + <note> + <para>É <emphasis>sempre</emphasis> incorreto definir qualquer <varname>USE_<replaceable>*</replaceable></varname> dentro de <filename>/etc/make.conf</filename>. Por exemplo, definindo </para> + + <programlisting>USE_GCC=X.Y</programlisting> + + <para>(onde XY é o número da versão) adicionaria uma dependência do gccXY para cada port, incluindo <literal>lang/gccXY</literal> em si!</para> + </note> + + <table frame="none" xml:id="makefile-use-vars-table"> + <title><varname>USE_<replaceable>*</replaceable></varname></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Significa</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>USE_GCC</varname></entry> + <entry>O port requer GCC (<command>gcc</command> ou <command>g++</command>) para compilar. Alguns ports precisam de qualquer versão do GCC, algumas exigem versões modernas e recentes. Normalmente, é configurado para <literal>qualquer</literal> (neste caso, o GCC da base seria usado em versões do FreeBSD que ainda o possuem, ou o port <literal>lang/gcc</literal> seria instalado quando o compilador C/C++ padrão for o Clang); ou <literal>yes</literal> (significa usar sempre GCC estável e moderno do port <literal>lang/gcc</literal>). A versão exata também pode ser especificada, com um valor como <literal>4.7</literal>. A versão mínima exigida pode ser especificada como <literal>4.6+</literal>. O GCC do sistema base é usado quando satisfaz a versão solicitada, caso contrário, um compilador apropriado é compilado a partir do port, e <varname>CC</varname> e <varname>CXX</varname> são ajustados em conformidade.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Variáveis relacionadas ao <application>gmake</application> e <filename>configure</filename> são descritos em <xref linkend="building"/>, enquanto <application>autoconf</application>, <application>automake </application> e <application>libtool</application> são descritos em <xref linkend="using-autotools"/>. Variáveis relacionadas ao <application>Perl</application> são descritas em <xref linkend="using-perl"/>. Variáveis X11 são listadas em <xref linkend="using-x11"/>. <xref linkend="using-gnome"/> lida com o GNOME e <xref linkend="using-kde"/> com variáveis relacionadas ao KDE. <xref linkend="using-java"/> documenta variáveis Java, enquanto <xref linkend="using-php"/> contém informações sobre <application>Apache</application>, <application>PHP</application> e módulos PEAR. <application>Python </application> é discutido em <xref linkend="using-python"/>, e <application>Ruby</application> em <xref linkend="using-ruby"/>. <xref linkend="using-sdl"/> fornece variáveis usadas para aplicações <application>SDL</application> e, finalmente, <xref linkend="using-xfce"/> contém informações sobre o <application>Xfce</application>.</para> + </sect2> + + <sect2 xml:id="makefile-version-dependency"> + <title>Versão Mínima de uma Dependência</title> + + <para>Uma versão mínima de uma dependência pode ser especificada em qualquer <varname><replaceable>*</replaceable>_DEPENDS</varname>, exceto <varname>LIB_DEPENDS</varname>, usando esta sintaxe:</para> + + <programlisting>p5-Spiffy>=0.26:devel/p5-Spiffy</programlisting> + + <para>O primeiro campo contém um nome de pacote dependente, que deve corresponder à entrada no banco de dados de pacotes, um sinal de comparação e uma versão do pacote. A dependência é satisfeita se o p5-Spiffy-0.26 ou mais recente estiver instalado na máquina.</para> + </sect2> + + <sect2 xml:id="makefile-note-on-dependencies"> + <title>Notas sobre Dependências</title> + + <para>Como mencionado acima, o target padrão para chamar quando uma dependência é necessária é o <buildtarget>DEPENDS_TARGET</buildtarget>. Seu padrão é o <literal>install</literal>. Esta é uma variável de usuário; nunca é definido em um <filename>Makefile</filename> de port. Se o port precisar de uma maneira especial de lidar com uma dependência, use a parte <literal>:target</literal> de <varname><replaceable>*</replaceable>_DEPENDS</varname> em vez de redefinir <varname>DEPENDS_TARGET</varname>.</para> + + <para>Quando rodar <command>make clean</command>, as dependências de port também são limpas automaticamente. Se isso não for desejável, defina <varname>NOCLEANDEPENDS</varname> no ambiente. Isto pode ser particularmente desejável se o port tiver algo que demore muito tempo para recompilar em sua lista de dependências, como o KDE, o GNOME ou o Mozilla.</para> + + <para>Para depender de outro port incondicionalmente, use a variável <literal>${NONEXISTENT}</literal> no primeiro campo do <varname>BUILD_DEPENDS</varname> ou <varname>RUN_DEPENDS</varname>. Use isto somente quando o código fonte do outro port for necessário. Tempo de compilação pode ser economizado especificando o target também. Por exemplo</para> + + <programlisting>BUILD_DEPENDS= ${NONEXISTENT}:graphics/jpeg:extract</programlisting> + + <para>sempre descerá para o port <literal>jpeg</literal> e extrai-lo. </para> + </sect2> + + <sect2 xml:id="makefile-circular-dependencies"> + <title>Dependências Circulares são Fatais</title> + + <important> + <para>Não insira nenhuma dependência circular na árvore de ports!</para> + </important> + + <para>A tecnologia de compilação de ports não tolera dependências circulares. Se uma for inserida, alguém, em algum lugar do mundo, terá sua instalação do FreeBSD quebrada quase que imediatamente, e muitos outros rapidamente terão o mesmo problema. Estes erros podem ser realmente difíceis de serem detectados. Em caso de dúvida, antes de fazer qualquer alteração, certifique-se de executar: <command>cd /usr/ports; make index</command>. Esse processo pode ser muito lento em máquinas mais antigas, mas pode evitar dor de cabeça para um grande número de pessoas, incluindo você.</para> + </sect2> + + <sect2 xml:id="makefile-automatic-dependencies"> + <title>Problemas Causados por Dependências Automáticas</title> + + <para>Dependências devem ser declaradas explicitamente ou usando o <link linkend="makefile-options">framework OPTIONS</link>. Usar outros métodos, como a detecção automática, dificulta a indexação, o que causa problemas para o gerenciamento de ports e pacotes.</para> + + <example xml:id="makefile-automatic-dependencies-bad"> + <title>Declaração Errada de uma Dependência Opcional</title> + + <programlisting>.include <bsd.port.pre.mk> + +.if exists(${LOCALBASE}/bin/foo) +LIB_DEPENDS= libbar.so:foo/bar +.endif</programlisting> + </example> + + <para>O problema em tentar adicionar dependências automaticamente é que os arquivos e configurações fora de um port individual podem ser alterados a qualquer momento. Por exemplo: um índice é construído, depois um lote de ports é instalado. Mas um dos ports instala o arquivo testado. O índice então fica incorreto, porque um port instalado inesperadamente tem uma nova dependência. O índice ainda pode estar errado mesmo após a recriação, se outros ports também determinarem a necessidade de dependências com base na existência de outros arquivos.</para> + + <example xml:id="makefile-automatic-dependencies-good"> + <title>Declaração Correta de uma Dependência Opcional</title> + + <programlisting>OPTIONS_DEFINE= BAR +BAR_DESC= Calling cellphones via bar + +BAR_LIB_DEPENDS= libbar.so:foo/bar</programlisting> + </example> + + <para>Testar variáveis de opções é o método correto. Ele não causará inconsistências no índice de um lote de ports, desde que as opções tenham sido definidas antes da construção do índice. Scripts simples podem ser usados para automatizar a compilação, instalação e atualização desses ports e seus pacotes.</para> + </sect2> + </sect1> + + <sect1 xml:id="makefile-masterdir"> + <title>Ports Slaves e <varname>MASTERDIR</varname></title> + + <para>Se o port precisar criar versões ligeiramente diferentes de pacotes fazendo com que uma variável (por exemplo, resolução ou tamanho de papel) assuma valores diferentes, crie um subdiretório por pacote para facilitar aos usuários a visualização do que fazer, mas tente compartilhar o máximo possível de arquivos entre os ports. Normalmente, usando variáveis inteligentemente, apenas um <filename>Makefile</filename> bem curto será necessário em todos, exceto em um dos diretórios. No <filename>Makefile</filename> solitário, use <varname>MASTERDIR</varname> para especificar o diretório onde o restante dos arquivos estão. Além disso, use uma variável como parte de <link linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link> para que os pacotes tenham nomes diferentes.</para> + + <para>Isso será melhor demonstrado por um exemplo. Isso é parte de <filename>print/pkfonts300/Makefile</filename>;</para> + + <programlisting>PORTNAME= pkfonts${RESOLUTION} +PORTVERSION= 1.0 +DISTFILES= pk${RESOLUTION}.tar.gz + +PLIST= ${PKGDIR}/pkg-plist.${RESOLUTION} + +.if !defined(RESOLUTION) +RESOLUTION= 300 +.else +.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ + ${RESOLUTION} != 300 && ${RESOLUTION} != 360 && \ + ${RESOLUTION} != 400 && ${RESOLUTION} != 600 +.BEGIN: + @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" + @${ECHO_MSG} "Possible values are: 118, 240, 300, 360, 400 and 600." + @${FALSE} +.endif +.endif</programlisting> + + <para><package role="port">print/pkfonts300</package> também tem todos os patches, arquivos de pacotes, etc. Rodando <command>make</command> nele, será assumido o valor padrão para a resolução (300) e o port será compilado normalmente.</para> + + <para>Quanto às outras resoluções, este é o <filename>print/pkfonts360/Makefile</filename> <emphasis>completo</emphasis>:</para> + + <programlisting>RESOLUTION= 360 +MASTERDIR= ${.CURDIR}/../pkfonts300 + +.include "${MASTERDIR}/Makefile"</programlisting> + + <para>(<filename>print/pkfonts118/Makefile</filename>, <filename>print/pkfonts600/Makefile</filename>, e todos os outros são semelhantes). A definição de <varname>MASTERDIR</varname> diz ao <filename>bsd.port.mk</filename> que o conjunto regular de subdiretórios como <varname>FILESDIR</varname> e <varname>SCRIPTDIR</varname> podem ser encontrados em <filename>pkfonts300</filename>. A linha <literal>RESOLUTION=360</literal> irá substituir a linha <literal>RESOLUTION=300</literal> em <filename>pkfonts300/Makefile</filename> e o port será compilado com a resolução definida para 360.</para> + </sect1> + + <sect1 xml:id="makefile-manpages"> + <title>Páginas de Manual</title> + + <para>Se o port instala a sua árvore de manuais em outro lugar diferente de <varname>PREFIX</varname>, use <varname>MANDIRS</varname> para especificar esses diretórios. Note que os arquivos correspondentes às páginas de manual devem ser colocados no <filename>pkg-plist</filename> junto com o resto dos arquivos. O propósito do <varname>MANDIRS</varname> é ativar a compactação automática de páginas de manual, portanto, os nomes dos arquivos são sufixados com <filename>.gz</filename>.</para> + </sect1> + + <sect1 xml:id="makefile-info"> + <title>Arquivos de Informação</title> + + <para>Se o pacote precisar instalar arquivos de informações <acronym>GNU</acronym>, liste-os na variável <varname>INFO</varname> (sem o sufixo <literal>.info</literal>), uma entrada por documento. Presume-se que esses arquivos estejam instalados em <filename>PREFIX/INFO_PATH</filename>. Mude <varname>INFO_PATH</varname> se o pacote usa um local diferente. Contudo, isto não é recomendado. Essas entradas contêm apenas o caminho relativo para <filename>PREFIX/INFO_PATH</filename>. Por exemplo, <package role="port">lang/gcc34</package> instala arquivos de informações em <filename>PREFIX/INFO_PATH/gcc34</filename> e <varname>INFO</varname> será algo assim:</para> + + <programlisting>INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ...</programlisting> + + <para>O código apropriado de instalação/desinstalação será automaticamente adicionado ao arquivo <filename>pkg-plist</filename> temporário antes do registro do pacote.</para> + </sect1> + + <sect1 xml:id="makefile-options"> + <title>Opções do Makefile</title> + + <para>Muitas aplicações podem ser compiladas com configurações opcionais ou diferentes. Exemplos podem ser a escolha de linguagem natural (humana), GUI versus linha de comando ou qual tipo de banco de dados será suportado. Os usuários podem precisar de uma configuração diferente do padrão, portanto o sistema de ports fornece ganchos em que o autor do port pode usar para controlar qual variante será compilada. Suportar essas opções corretamente fará com que os usuários fiquem felizes, e efetivamente forneça dois ou mais ports pelo preço de um.</para> + + <sect2 xml:id="makefile-options-options"> + <title><varname>OPTIONS</varname></title> + + <sect3 xml:id="makefile-options-background"> + <title>Background</title> + + <para><varname>OPTIONS_<replaceable>*</replaceable></varname> fornece ao usuário que está instalando o port uma caixa de diálogo mostrando as opções disponíveis e, em seguida, salva essas opções em <filename>${PORT_DBDIR}/${OPTIONS_NAME}/options</filename>. Na próxima vez que o port for compilado, as opções serão reutilizadas. O padrão de <varname>PORT_DBDIR</varname> é <filename>/var/db/ports</filename>. <varname>OPTIONS_NAME</varname> é a origem do port com um underline como o separador de espaço, por exemplo, <package role="port">dns/bind99</package> será <literal>dns_bind99</literal>.</para> + + <para>Quando o usuário executa <command>make config</command> (ou executa <command>make build</command> pela primeira vez), o framework verifica <filename>${PORT_DBDIR}/${OPTIONS_NAME}/options</filename>. Se esse arquivo não existir, os valores de <varname>OPTIONS_<replaceable>*</replaceable></varname> são usados e uma caixa de diálogo é exibida onde as opções podem ser ativadas ou desativadas. Então as <filename>options</filename> são salvas e as variáveis configuradas são utilizadas ao compilar o port.</para> + + <para>Se uma nova versão do port adicionar novas <varname>OPTIONS</varname>, a caixa de diálogo será apresentada ao usuário, já preenchido com os valores salvos das antigas <varname>OPTIONS</varname>.</para> + + <para><command>make showconfig</command> mostra a configuração salva. Use <command>make rmconfig</command> para remover a configuração salva.</para> + </sect3> + + <sect3 xml:id="makefile-options-syntax"> + <title>Sintaxe</title> + + <para><varname>OPTIONS_DEFINE</varname> contém uma lista de <varname>OPTIONS</varname> para serem utilizadas. Elas são independentes umas das outras e não são agrupadas:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2</programlisting> + + <para>Uma vez definido, as <varname>OPTIONS</varname> são descritas (opcionalmente, mas fortemente recomendado):</para> + + <programlisting>OPT1_DESC= Describe OPT1 +OPT2_DESC= Describe OPT2 +OPT3_DESC= Describe OPT3 +OPT4_DESC= Describe OPT4 +OPT5_DESC= Describe OPT5 +OPT6_DESC= Describe OPT6</programlisting> + + <para><filename>ports/Mk/bsd.options.desc.mk</filename> possui descrições para muitas <varname>OPTIONS</varname> comuns. Geralmente são úteis, mas podem ser substituas se a descrição for insuficiente para o port.</para> + + <tip> + <para>Ao descrever as opções, visualize-as da perspectiva do usuário: <quote>Qual funcionalidade ela muda?</quote> e <quote>Por que eu iria querer habilitar ela?</quote> Não repita apenas o nome. Por exemplo, descrever a opção <literal>NLS</literal> como <quote>incluir suporte NLS</quote> não ajuda o usuário, que já pode ver o nome da opção, mas pode não saber o que isso significa. Descrevendo-a como <quote>Suporte a idiomas nativos por meio de utilitários gettext</quote> é muito mais útil.</para> + </tip> + + <important> + <para>Os nomes das opções são sempre em letras maiúsculas. Não podem estar misturadas ou apenas em minúsculo.</para> + </important> + + <para><varname>OPTIONS</varname> podem ser agrupadas como opções radio, onde apenas uma escolha de cada grupo é permitida:</para> + + <programlisting>OPTIONS_SINGLE= SG1 +OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting> + + <warning> + <para><emphasis>Deve</emphasis> estar sempre selecionada uma de cada <literal>OPTIONS_SINGLE</literal> para as opções serem válidas. Uma opção de cada grupo <emphasis>deve</emphasis> ser adicionada a <varname>OPTIONS_DEFAULT</varname>.</para> + </warning> + + <para><varname>OPTIONS</varname> podem ser agrupadas como opções radio, onde nenhuma ou apenas uma escolha de cada grupo é permitida:</para> + + <programlisting>OPTIONS_RADIO= RG1 +OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting> + + <para><varname>OPTIONS</varname> também pode ser agrupadas como listas de <quote>múltipla-escolha</quote>, onde <emphasis>pelo menos uma</emphasis> opção deve estar habilitada:</para> + + <programlisting>OPTIONS_MULTI= MG1 +OPTIONS_MULTI_MG1= OPT5 OPT6</programlisting> + + <para><varname>OPTIONS</varname> também pode ser agrupadas como listas de <quote>múltipla-escolha</quote>, onde nenhuma ou qualquer opção pode ser ativada:</para> + + <programlisting>OPTIONS_GROUP= GG1 +OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting> + + <para><varname>OPTIONS</varname> são desativadas por padrão, a menos que estejam listadas em <varname>OPTIONS_DEFAULT</varname>:</para> + + <programlisting>OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting> + + <para>Definições de <varname>OPTIONS</varname> devem aparecer antes da inclusão de <filename>bsd.port.options.mk</filename>. Valores de <varname>PORT_OPTIONS</varname> só podem ser testados após a inclusão de <filename>bsd.port.options.mk</filename>. Inclusão de <filename>bsd.port.pre.mk</filename> pode ser usado também, e ainda é amplamente usado em ports escritos antes da introdução de <filename>bsd.port.options.mk</filename>. Mas esteja ciente de que algumas variáveis não funcionarão como esperado após a inclusão de <filename>bsd.port.pre.mk</filename>, tipicamente algumas flags <varname>USE_<replaceable>*</replaceable></varname>.</para> + + <example xml:id="ports-options-simple-use"> + <title>Uso Simples de <varname>OPTIONS</varname></title> + + <programlisting>OPTIONS_DEFINE= FOO BAR +FOO_DESC= Option foo support +BAR_DESC= Feature bar support + +OPTIONS_DEFAULT=FOO + +# Will add --with-foo/--without-foo +FOO_CONFIGURE_WITH= foo +BAR_RUN_DEPENDS= bar:bar/bar + +.include <bsd.port.mk></programlisting> + </example> + + <example xml:id="ports-options-check-unset"> + <title>Verificar <varname>OPTIONS</varname> Desmacadas</title> + + <programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES} +CONFIGURE_ARGS+=--without-examples +.endif</programlisting> + + <para>O formato acima não é recomendado. O método preferido é usar um configure knob para realmente ativar e desativar o recurso coincidindo com a opção:</para> + + <programlisting># Will add --with-examples / --without-examples +EXAMPLES_CONFIGURE_WITH= examples</programlisting> + </example> + + <example xml:id="ports-options-practical-use"> + <title>Uso Prático de <varname>OPTIONS</varname></title> + + <programlisting>OPTIONS_DEFINE= EXAMPLES + +OPTIONS_SINGLE= BACKEND +OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB + +OPTIONS_MULTI= AUTH +OPTIONS_MULTI_AUTH= LDAP PAM SSL + +EXAMPLES_DESC= Install extra examples +MYSQL_DESC= Use MySQL as backend +PGSQL_DESC= Use PostgreSQL as backend +BDB_DESC= Use Berkeley DB as backend +LDAP_DESC= Build with LDAP authentication support +PAM_DESC= Build with PAM support +SSL_DESC= Build with OpenSSL support + +OPTIONS_DEFAULT= PGSQL LDAP SSL + +# Will add USE_PGSQL=yes +PGSQL_USE= pgsql=yes +# Will add --enable-postgres/--disable-postgres +PGSQL_CONFIGURE_ENABLE= postgres + +ICU_LIB_DEPENDS= libicuuc.so:devel/icu + +# Will add --with-examples/--without-examples +EXAMPLES_CONFIGURE_WITH= examples + +# Check other OPTIONS + +.include <bsd.port.mk></programlisting> + </example> + </sect3> + + <sect3 xml:id="makefile-options-default"> + <title>Opções Padrão</title> + + <para>Essas opções estão sempre ativadas por padrão.</para> + + <itemizedlist> + <listitem> + <para><literal>DOCS</literal> — build and install documentation.</para> + </listitem> + + <listitem> + <para><literal>NLS</literal> — Native Language Support.</para> + </listitem> + + <listitem> + <para><literal>EXAMPLES</literal> — build and install examples.</para> + </listitem> + + <listitem> + <para><literal>IPV6</literal> — IPv6 protocol support.</para> + </listitem> + </itemizedlist> + + <note> + <para>Não há necessidade de adicioná-las em <varname>OPTIONS_DEFAULT</varname>. Para ativá-las e mostra-las na caixa de diálogo de seleção de opções, elas devem ser adicionadas em <varname>OPTIONS_DEFINE</varname>.</para> + </note> + </sect3> + </sect2> + + <sect2 xml:id="makefile-options-auto-activation"> + <title>Feature de Ativação Automática</title> + + <para>Ao usar um script configure GNU, fique de olho em quais recursos opcionais são ativados por detecção automática. Desative explicitamente os recursos opcionais que não são necessários, adicionando <literal>--without-xxx</literal> ou <literal>--disable-xxx</literal> em <varname>CONFIGURE_ARGS</varname>.</para> + + <example xml:id="makefile-options-auto-activation-bad"> + <title>Manipulação Incorreta de uma Opção</title> + + <programlisting>.if ${PORT_OPTIONS:MFOO} +LIB_DEPENDS+= libfoo.so:devel/foo +CONFIGURE_ARGS+= --enable-foo +.endif</programlisting> + </example> + + <para>No exemplo acima, imagine que uma biblioteca libfoo está instalada no sistema. O usuário não quer que este aplicativo use libfoo, então ele desabilitou a opção na caixa de diálogo do <literal>make config</literal>. Mas o script configure do aplicativo detecta a biblioteca presente no sistema e inclui seu suporte no executável resultante. Agora, quando o usuário decide remover libfoo do sistema, o sistema de ports não protesta (nenhuma dependência de libfoo foi registrada), e então o aplicativo quebra.</para> + + <example xml:id="makefile-options-auto-activation-good"> + <title>Manuseio Correto de uma Opção</title> + + <programlisting>FOO_LIB_DEPENDS= libfoo.so:devel/foo +# Will add --enable-foo / --disable-foo +FOO_CONFIGURE_ENABLE= foo</programlisting> + </example> + + <note> + <para>Sob algumas circunstâncias, a sintaxe condicional abreviada pode causar problemas com construções complexas. Os erros são geralmente <literal>Malformed conditional</literal>, e uma sintaxe alternativa pode ser usada.</para> + + <programlisting>.if !empty(VARIABLE:MVALUE)</programlisting> + + <para>como uma alternativa para</para> + + <programlisting>.if ${VARIABLE:MVALUE}</programlisting> + </note> + </sect2> + + <sect2 xml:id="options-helpers"> + <title>Assistentes de Opções</title> + + <para>Existem algumas macros para ajudar a simplificar valores condicionais que diferem com base nas opções definidas. Para facilitar o acesso, é fornecida uma lista abrangente:</para> + + <variablelist xml:id="options-helpers-list"> + <varlistentry> + <term><varname>PLIST_SUB</varname>, <varname>SUB_LIST</varname></term> + + <listitem> + <para>Para geração automática de <literal>%%<replaceable>OPT</replaceable>%%</literal> e <literal>%%NO_<replaceable>OPT</replaceable>%%</literal>, veja <xref linkend="options_sub"/>.</para> + + <para>Para uso mais complexo, veja <xref linkend="options-variables"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>CONFIGURE_ARGS</varname></term> + + <listitem> + <para>Para <literal>--enable-<replaceable>x</replaceable></literal> e <literal>--disable-<replaceable>x</replaceable></literal>, veja <xref linkend="options-configure_enable"/>.</para> + + <para>Para <literal>--with-<replaceable>x</replaceable></literal> e <literal>--without-<replaceable>x</replaceable></literal>, veja <xref linkend="options-configure_with"/>.</para> + + <para>Para todos os outros casos, veja <xref linkend="options-configure_on"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>CMAKE_ARGS</varname></term> + + <listitem> + <para>Para argumentos que são booleanos (<literal>on</literal>, <literal>off</literal>, <literal>true</literal>, <literal>false</literal>, <literal>0</literal>, <literal>1</literal>) veja <xref linkend="options-cmake_bool"/>.</para> + + <para>Para todos os outros casos, veja <xref linkend="options-cmake_on"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MESON_ARGS</varname></term> + <listitem> + <para>Para argumentos que precisam de <literal>true</literal> ou <literal>false</literal>, veja <xref linkend="options-meson_true"/>.</para> + + <para>Para argumentos que precisam de <literal>yes</literal> ou <literal>no</literal>, use <xref linkend="options-meson_yes"/>.</para> + + <para>Para todos os outros casos, use <xref linkend="options-meson_on"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>QMAKE_ARGS</varname></term> + + <listitem> + <para>Veja <xref linkend="options-qmake_on"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>USE_<replaceable>*</replaceable></varname></term> + + <listitem> + <para>Veja <xref linkend="options-use"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname><replaceable>*</replaceable>_DEPENDS</varname></term> + + <listitem> + <para>Veja <xref linkend="options-dependencies"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>*</replaceable> (Qualquer variável)</term> + + <listitem> + <para>As variáveis mais usadas possuem assistentes diretos, veja <xref linkend="options-variables"/>.</para> + + <para>Para qualquer variável sem um assistente específico, veja <xref linkend="options-vars"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Dependências de opções</term> + + <listitem> + <para>Quando uma opção precisa de outra opção para funcionar, veja <xref linkend="options-implies"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Conflitos de opções</term> + + <listitem> + <para>Quando uma opção não funciona se outra também estiver ativada, consulte <xref linkend="options-prevents"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Targets para Build</term> + + <listitem> + <para>Quando uma opção precisa de algum processamento extra, veja <xref linkend="options-targets"/>.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3 xml:id="options_sub"> + <title><varname>OPTIONS_SUB</varname></title> + + <para>Se <varname>OPTIONS_SUB</varname> está definido com <literal>yes</literal> então cada uma das opções adicionadas a <varname>OPTIONS_DEFINE</varname> será adicionada em <varname>PLIST_SUB</varname> e <varname>SUB_LIST</varname>, por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPTIONS_SUB= yes</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +PLIST_SUB+= OPT1="" NO_OPT1="@comment " +SUB_LIST+= OPT1="" NO_OPT1="@comment " +.else +PLIST_SUB+= OPT1="@comment " NO_OPT1="" +SUB_LIST+= OPT1="@comment " NO_OPT1="" +.endif</programlisting> + + <note> + <para>O valor de <varname>OPTIONS_SUB</varname> é ignorado. Definindo-o com qualquer valor irá adicionar entradas <varname>PLIST_SUB</varname> e <varname>SUB_LIST</varname> para <emphasis>todas</emphasis> as opções.</para> + </note> + </sect3> + + <sect3 xml:id="options-use"> + <title><varname><replaceable>OPT</replaceable>_USE</varname> e <varname><replaceable>OPT</replaceable>_USE_OFF</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, para cada par <literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal> em <varname><replaceable>OPT</replaceable>_USE</varname>, <replaceable>value</replaceable> é anexado ao <varname>USE_<replaceable>KEY</replaceable></varname> correspondente. E se <replaceable>value</replaceable> tiver espaços, substitua-os por vírgulas e eles serão alterados de volta para espaços durante o processamento. <varname><replaceable>OPT</replaceable>_USE_OFF</varname> funciona da mesma maneira, quando <literal>OPT</literal> <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_USE= mysql=yes xorg=x11,xextproto,xext,xrandr +OPT1_USE_OFF= openssl=yes</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +USE_MYSQL= yes +USE_XORG= x11 xextproto xext xrandr +.else +USE_OPENSSL= yes +.endif</programlisting> + </sect3> + + <sect3 xml:id="options-configure-helpers"> + <title>Assistentes <varname>CONFIGURE_ARGS</varname></title> + + <sect4 xml:id="options-configure_enable"> + <title><varname><replaceable>OPT</replaceable>_CONFIGURE_ENABLE</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, para cada <replaceable>valor</replaceable> em <varname><replaceable>OPT</replaceable>_CONFIGURE_ENABLE</varname>, <literal>--enable-<replaceable>valor</replaceable></literal> será anexado a <varname>CONFIGURE_ARGS</varname>. Quando a opção <replaceable>OPT</replaceable> <emphasis>não for</emphasis> selecionada, <literal>--disable-<replaceable>valor</replaceable></literal> será anexado a <varname>CONFIGURE_ARGS</varname>. Um argumento opcional pode ser especificado com um símbolo <literal>=</literal>. Este argumento é apenas anexado na entrada de opção do script configure <literal>--enable-<replaceable>valor</replaceable></literal>. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 +OPT1_CONFIGURE_ENABLE= test1 test2 +OPT2_CONFIGURE_ENABLE= test2=exhaustive</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --enable-test1 --enable-test2 +.else +CONFIGURE_ARGS+= --disable-test1 --disable-test2 +.endif + +.if ${PORT_OPTIONS:MOPT2} +CONFIGURE_ARGS+= --enable-test2=exhaustive +.else +CONFIGURE_ARGS+= --disable-test2 +.endif</programlisting> + </sect4> + + <sect4 xml:id="options-configure_with"> + <title><varname><replaceable>OPT</replaceable>_CONFIGURE_WITH</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, para cada <replaceable>valor</replaceable> em <varname><replaceable>OPT</replaceable>_CONFIGURE_WITH</varname>, <literal>--with-<replaceable>valor</replaceable></literal> será anexado a <varname>CONFIGURE_ARGS</varname>. Quando a opção <replaceable>OPT</replaceable> <emphasis>não for</emphasis> selecionada, <literal>--without-<replaceable>valor</replaceable></literal> será anexado a <varname>CONFIGURE_ARGS</varname>. Um argumento opcional pode ser especificado com um símbolo <literal>=</literal>. Este argumento é apenas anexado na entrada de opção do script configure <literal>--with-<replaceable>valor</replaceable></literal>. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 +OPT1_CONFIGURE_WITH= test1 +OPT2_CONFIGURE_WITH= test2=exhaustive</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --with-test1 +.else +CONFIGURE_ARGS+= --without-test1 +.endif + +.if ${PORT_OPTIONS:MOPT2} +CONFIGURE_ARGS+= --with-test2=exhaustive +.else +CONFIGURE_ARGS+= --without-test2 +.endif</programlisting> + </sect4> + + <sect4 xml:id="options-configure_on"> + <title><varname><replaceable>OPT</replaceable>_CONFIGURE_ON</varname> e <varname><replaceable>OPT</replaceable>_CONFIGURE_OFF</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, o valor de <varname><replaceable>OPT</replaceable>_CONFIGURE_ON</varname>, se definido, é anexado a <varname>CONFIGURE_ARGS</varname>. <varname><replaceable>OPT</replaceable>_CONFIGURE_OFF</varname> funciona da mesma maneira, quando <literal>OPT</literal><emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CONFIGURE_ON= --add-test +OPT1_CONFIGURE_OFF= --no-test</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --add-test +.else +CONFIGURE_ARGS+= --no-test +.endif</programlisting> + + <tip> + <para>Na maioria das vezes, os assistentes em <xref linkend="options-configure_enable"/> e <xref linkend="options-configure_with"/> fornecem uma funcionalidade mais curta e abrangente. </para> + </tip> + </sect4> + </sect3> + + <sect3 xml:id="options-cmake-helpers"> + <title>Assistentes <varname>CMAKE_ARGS</varname></title> + + <sect4 xml:id="options-cmake_on"> + <title><varname><replaceable>OPT</replaceable>_CMAKE_ON</varname> e <varname><replaceable>OPT</replaceable>_CMAKE_OFF</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, o valor de <varname><replaceable>OPT</replaceable>_CMAKE_ON</varname>, se definido, é anexado a <varname>CMAKE_ARGS</varname>. <varname><replaceable>OPT</replaceable>_CMAKE_OFF</varname> funciona da mesma maneira, mas quando <literal>OPT</literal> <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CMAKE_ON= -DTEST:BOOL=true -DDEBUG:BOOL=true +OPT1_CMAKE_OFF= -DOPTIMIZE:BOOL=true</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CMAKE_ARGS+= -DTEST:BOOL=true -DDEBUG:BOOL=true +.else +CMAKE_ARGS+= -DOPTIMIZE:BOOL=true +.endif</programlisting> + + <tip> + <para>Veja <xref linkend="options-cmake_bool"/> para um assistente mais curto quando o valor for booleano. </para> + </tip> + </sect4> + + <sect4 xml:id="options-cmake_bool"> + <title><varname><replaceable>OPT</replaceable>_CMAKE_BOOL</varname> e <varname><replaceable>OPT</replaceable>_CMAKE_BOOL_OFF</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, para cada <replaceable>valor</replaceable> em <varname><replaceable>OPT</replaceable>_CMAKE_BOOL</varname>, <literal>-D<replaceable>valor</replaceable>:BOOL=true</literal> será anexado a <varname>CMAKE_ARGS</varname>. Quando a opção <replaceable>OPT</replaceable> <emphasis>não for</emphasis> selecionada, <literal>-D<replaceable>valor</replaceable>:BOOL=false</literal> será anexado a <varname>CONFIGURE_ARGS</varname>. <varname><replaceable>OPT</replaceable>_CMAKE_BOOL_OFF</varname> é o oposto, <literal>-D<replaceable>valor</replaceable>:BOOL=false</literal> será anexado a <varname>CMAKE_ARGS</varname> quando a opção é selecionada, e a entrada <literal>-D<replaceable>valor</replaceable>:BOOL=true</literal> quando a opção <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CMAKE_BOOL= TEST DEBUG +OPT1_CMAKE_BOOL_OFF= OPTIMIZE</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CMAKE_ARGS+= -DTEST:BOOL=true -DDEBUG:BOOL=true \ + -DOPTIMIZE:BOOL=false +.else +CMAKE_ARGS+= -DTEST:BOOL=false -DDEBUG:BOOL=false \ + -DOPTIMIZE:BOOL=true +.endif</programlisting> + </sect4> + </sect3> + + <sect3 xml:id="options-meson-helpers"> + <title>Assistentes <varname>MESON_ARGS</varname></title> + + <sect4 xml:id="options-meson_on"> + <title><varname><replaceable>OPT</replaceable>_MESON_ON</varname> e <varname><replaceable>OPT</replaceable>_MESON_OFF</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, o valor de <varname><replaceable>OPT</replaceable>_MESON_ON</varname>, se definido, é anexado a <varname>MESON_ARGS</varname>. <varname><replaceable>OPT</replaceable>_MESON_OFF</varname> funciona da mesma maneira, quando <literal>OPT</literal> <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_MESON_ON= -Dopt=1 +OPT1_MESON_OFF= -Dopt=2</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +MESON_ARGS+= -Dopt=1 +.else +MESON_ARGS+= -Dopt=2 +.endif</programlisting> + </sect4> + + <sect4 xml:id="options-meson_true"> + <title><varname><replaceable>OPT</replaceable>_MESON_TRUE</varname> e <varname><replaceable>OPT</replaceable>_MESON_FALSE</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, para cada <replaceable>valor</replaceable> em <varname><replaceable>OPT</replaceable>_MESON_TRUE</varname>, <literal>-D<replaceable>valor</replaceable>=true</literal> será anexado a <varname>CMAKE_ARGS</varname>. Quando a opção <replaceable>OPT</replaceable> <emphasis>não for</emphasis> selecionada, <literal>-D<replaceable>valor</replaceable>=false</literal> será anexado a <varname>CONFIGURE_ARGS</varname>. <varname><replaceable>OPT</replaceable>_MESON_FALSE</varname> é o oposto, a entrada <literal>-D<replaceable>valor</replaceable>=false</literal> será anexado a <varname>CMAKE_ARGS</varname> quando a opção for selecionada e a entrada <literal>-D<replaceable>valor</replaceable>=true</literal> quando a opção <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_MESON_TRUE= test debug +OPT1_MESON_FALSE= optimize</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +MESON_ARGS+= -Dtest=true -Ddebug=true \ + -Doptimize=false +.else +MESON_ARGS+= -Dtest=false -Ddebug=false \ + -Doptimize=true +.endif</programlisting> + </sect4> + + <sect4 xml:id="options-meson_yes"> + <title><varname><replaceable>OPT</replaceable>_MESON_YES</varname> e <varname><replaceable>OPT</replaceable>_MESON_NO</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, para cada <replaceable>entrada</replaceable> dentro da variável <varname><replaceable>OPT</replaceable>_MESON_YES</varname> a entrada <literal>-D<replaceable/>=yes</literal> é anexada a variável <varname>CMAKE_ARGS</varname>. Quando a opção <replaceable>OPT</replaceable><emphasis>não é </emphasis> selecionada, então a entrada <literal>-D<replaceable/>=no</literal> é anexada a variável <varname>CONFIGURE_ARGS</varname>. <varname><replaceable>OPT</replaceable>_MESON_NO</varname> é o oposto, a entrada <literal>-D<replaceable/>=no</literal> é anexada a variável <varname>CMAKE_ARGS</varname> quando a opção é selecionada e a entrada <literal>-D<replaceable/>=yes</literal> quando a opção <emphasis>não é</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_MESON_YES= test debug +OPT1_MESON_NO= optimize</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CMAKE_ARGS+= -Dtest=yes -Ddebug=yes \ + -Doptimize=no +.else +CMAKE_ARGS+= -Dtest=no -Ddebug=no \ + -Doptimize=yes +.endif</programlisting> + </sect4> + </sect3> + + <sect3 xml:id="options-qmake_on"> + <title><varname><replaceable>OPT</replaceable>_QMAKE_ON</varname> e <varname><replaceable>OPT</replaceable>_QMAKE_OFF</varname></title> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, o valor de <varname><replaceable>OPT</replaceable>_QMAKE_ON</varname>, se definido, é anexado a <varname>QMAKE_ARGS</varname>. <varname><replaceable>OPT</replaceable>_QMAKE_OFF</varname> funciona da mesma maneira, quando <literal>OPT</literal> <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_QMAKE_ON= -DTEST:BOOL=true +OPT1_QMAKE_OFF= -DPRODUCTION:BOOL=true</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +QMAKE_ARGS+= -DTEST:BOOL=true +.else +QMAKE_ARGS+= -DPRODUCTION:BOOL=true +.endif</programlisting> + </sect3> + + <sect3 xml:id="options-implies"> + <title><varname><replaceable>OPT</replaceable>_IMPLIES</varname></title> + + <para>Fornece uma maneira de adicionar dependências entre as opções.</para> + + <para>Quando <replaceable>OPT</replaceable> for selecionada, todas as opções listadas nesta variável também serão selecionadas. Usando o <link linkend="options-configure_enable"><varname><replaceable>OPT</replaceable>_CONFIGURE_ENABLE</varname></link> descrito anteriormente para demonstrar: </para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 +OPT1_IMPLIES= OPT2 + +OPT1_CONFIGURE_ENABLE= opt1 +OPT2_CONFIGURE_ENABLE= opt2</programlisting> + + <para>É equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --enable-opt1 +.else +CONFIGURE_ARGS+= --disable-opt1 +.endif + +.if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --enable-opt2 +.else +CONFIGURE_ARGS+= --disable-opt2 +.endif</programlisting> + + <example xml:id="options-implies-ex1"> + <title>Uso Simples de <varname><replaceable>OPT</replaceable>_IMPLIES</varname></title> + + <para>Este port tem uma opção <literal>X11</literal> e uma opção <literal>GNOME</literal> que precisa da opção <literal>X11</literal> selecionada para poder compilar.</para> + + <programlisting>OPTIONS_DEFINE= X11 GNOME +OPTIONS_DEFAULT= X11 + +X11_USE= xorg=xi,xextproto +GNOME_USE= gnome=gtk30 +GNOME_IMPLIES= X11</programlisting> + </example> + </sect3> + + <sect3 xml:id="options-prevents"> + <title><varname><replaceable>OPT</replaceable>_PREVENTS</varname> e <varname><replaceable>OPT</replaceable>_PREVENTS_MSG</varname></title> + + <para>Fornece uma maneira de adicionar conflitos entre as opções.</para> + + <para>Quando <replaceable>OPT</replaceable> for selecionada, todas as opções listadas nessa variável devem estar desmarcadas. E se <varname><replaceable>OPT</replaceable>_PREVENTS_MSG</varname> estiver definido, seu conteúdo será exibido, explicando o por que do conflito. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 +OPT1_PREVENTS= OPT2 +OPT1_PREVENTS_MSG= OPT1 and OPT2 enable conflicting options</programlisting> + + <para>É aproximadamente equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT2} && ${PORT_OPTIONS:MOPT1} +BROKEN= Option OPT1 conflicts with OPT2 (select only one) +.endif</programlisting> + + <para>A única diferença é que o primeiro irá apresentar um erro depois de executar <command>make config</command>, sugerindo alterar as opções selecionadas. </para> + + <example xml:id="options-prevents-ex1"> + <title>Uso Simples de <varname><replaceable>OPT</replaceable>_PREVENTS</varname></title> + + <para>Este port tem as opções <literal>X509</literal> e <literal>SCTP</literal>. Ambas as opções adicionam patches, mas os patches entram em conflito uns com os outros, então eles não podem ser selecionados ao mesmo tempo. </para> + + <programlisting>OPTIONS_DEFINE= X509 SCTP + +SCTP_PATCHFILES= ${PORTNAME}-6.8p1-sctp-2573.patch.gz:-p1 +SCTP_CONFIGURE_WITH= sctp + +X509_PATCH_SITES= http://www.roumenpetrov.info/openssh/x509/:x509 +X509_PATCHFILES= ${PORTNAME}-7.0p1+x509-8.5.diff.gz:-p1:x509 +X509_PREVENTS= SCTP +X509_PREVENTS_MSG= X509 and SCTP patches conflict</programlisting> + </example> + </sect3> + + <sect3 xml:id="options-vars"> + <title><varname><replaceable>OPT</replaceable>_VARS</varname> e <varname><replaceable>OPT</replaceable>_VARS_OFF</varname></title> + + <para>Fornece uma maneira genérica de definir e acrescentar valores em variáveis.</para> + + <warning><para>Antes de usar <varname><replaceable>OPT</replaceable>_VARS</varname> e <varname><replaceable>OPT</replaceable>_VARS_OFF</varname>, veja se já não existe um assistente mais específico disponível em <xref linkend="options-variables"/>.</para></warning> + + <para>Quando a opção <replaceable>OPT</replaceable> está selecionada e <varname><replaceable>OPT</replaceable>_VARS</varname> definido, os pares <literal><replaceable>chave</replaceable>=<replaceable>valor</replaceable></literal> e <literal> <replaceable>chave</replaceable>+=<replaceable>valor</replaceable></literal> são avaliados a partir da variável <varname><replaceable>OPT</replaceable>_VARS</varname>. Um <literal>=</literal> sobrescreve o valor existente da <literal>CHAVE</literal>, um <literal>+=</literal> acrescenta o valor a chave. <varname><replaceable>OPT</replaceable>_VARS_OFF</varname> funciona da mesma maneira, quando a opção <literal>OPT</literal> <emphasis>não for</emphasis> selecionada.</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 OPT3 +OPT1_VARS= also_build+=bin1 +OPT2_VARS= also_build+=bin2 +OPT3_VARS= bin3_build=yes +OPT3_VARS_OFF= bin3_build=no + +MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}"</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2 + +MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}" + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +ALSO_BUILD+= bin1 +.endif + +.if ${PORT_OPTIONS:MOPT2} +ALSO_BUILD+= bin2 +.endif + +.if ${PORT_OPTIONS:MOPT2} +BIN3_BUILD= yes +.else +BIN3_BUILD= no +.endif</programlisting> + + <important> + <para>Valores contendo espaços em branco devem ser colocados entre aspas:</para> + + <programlisting>OPT_VARS= foo="bar baz"</programlisting> + + <para>Isso se deve ao jeito que a variável de expansão <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> lida com espaço em branco. Quando a opção <literal>OPT_VARS=foo=bar baz</literal> é expandida, a variável acaba contendo duas strings, <literal>foo=bar</literal> e <literal>baz</literal>. Mas quem está submetendo o código provavelmente pretendia que houvesse apenas uma string, <literal>foo=bar baz</literal>. Inserir o valor entre aspas impede que o espaço em branco seja usado como um delimitador. </para> + + <para>Além disso, <emphasis>não</emphasis> adicione espaços extras após o símbolo <literal><replaceable>var</replaceable>=</literal> e antes do valor, pois assim também seria dividido o valor em duas strings. <emphasis>Isso não irá funcionar</emphasis>:</para> + + <programlisting>OPT_VARS= foo= bar</programlisting> + </important> + </sect3> + + <sect3 xml:id="options-dependencies"> + <title>Dependências, <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable></varname> e <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable>_OFF</varname></title> + + <para>Para qualquer um desses tipos de dependência:</para> + + <itemizedlist> + <listitem> + <para><varname>PKG_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>EXTRACT_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>PATCH_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>FETCH_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>BUILD_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>LIB_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>RUN_DEPENDS</varname></para> + </listitem> + </itemizedlist> + + <para>Quando opção <replaceable>OPT</replaceable> é selecionada, o valor de <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable></varname>, se definido, é anexado a <literal><replaceable>DEPTYPE</replaceable></literal>. <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable>_OFF</varname> funciona da mesma forma, quando <literal>OPT</literal> <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_LIB_DEPENDS= liba.so:devel/a +OPT1_LIB_DEPENDS_OFF= libb.so:devel/b</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +LIB_DEPENDS+= liba.so:devel/a +.else +LIB_DEPENDS+= libb.so:devel/b +.endif</programlisting> + </sect3> + + <sect3 xml:id="options-variables"> + <title>Substituição de Variáveis Genéricas, <varname><replaceable>OPT</replaceable>_<replaceable>VARIABLE</replaceable></varname> e <varname><replaceable>OPT</replaceable>_<replaceable>VARIABLE</replaceable>_OFF</varname></title> + + <para>Para qualquer uma destas variáveis:</para> + + <!-- + $ for i in $(make -V _OPTIONS_FLAGS:O); do printf '<listitem>\n<para><varname>%s</varname></para>\n</listitem>\n\n' $i; done + --> + + <itemizedlist> + <listitem> + <para><varname>ALL_TARGET</varname></para> + </listitem> + + <listitem> + <para><varname>BINARY_ALIAS</varname></para> + </listitem> + + <listitem> + <para><varname>BROKEN</varname></para> + </listitem> + + <listitem> + <para><varname>CATEGORIES</varname></para> + </listitem> + + <listitem> + <para><varname>CFLAGS</varname></para> + </listitem> + + <listitem> + <para><varname>CONFIGURE_ENV</varname></para> + </listitem> + + <listitem> + <para><varname>CONFLICTS</varname></para> + </listitem> + + <listitem> + <para><varname>CONFLICTS_BUILD</varname></para> + </listitem> + + <listitem> + <para><varname>CONFLICTS_INSTALL</varname></para> + </listitem> + + <listitem> + <para><varname>CPPFLAGS</varname></para> + </listitem> + + <listitem> + <para><varname>CXXFLAGS</varname></para> + </listitem> + + <listitem> + <para><varname>DESKTOP_ENTRIES</varname></para> + </listitem> + + <listitem> + <para><varname>DISTFILES</varname></para> + </listitem> + + <listitem> + <para><varname>EXTRACT_ONLY</varname></para> + </listitem> + + <listitem> + <para><varname>EXTRA_PATCHES</varname></para> + </listitem> + + <listitem> + <para><varname>GH_ACCOUNT</varname></para> + </listitem> + + <listitem> + <para><varname>GH_PROJECT</varname></para> + </listitem> + + <listitem> + <para><varname>GH_SUBDIR</varname></para> + </listitem> + + <listitem> + <para><varname>GH_TAGNAME</varname></para> + </listitem> + + <listitem> + <para><varname>GH_TUPLE</varname></para> + </listitem> + + <listitem> + <para><varname>GL_ACCOUNT</varname></para> + </listitem> + + <listitem> + <para><varname>GL_COMMIT</varname></para> + </listitem> + + <listitem> + <para><varname>GL_PROJECT</varname></para> + </listitem> + + <listitem> + <para><varname>GL_SITE</varname></para> + </listitem> + + <listitem> + <para><varname>GL_SUBDIR</varname></para> + </listitem> + + <listitem> + <para><varname>GL_TUPLE</varname></para> + </listitem> + + <listitem> + <para><varname>IGNORE</varname></para> + </listitem> + + <listitem> + <para><varname>INFO</varname></para> + </listitem> + + <listitem> + <para><varname>INSTALL_TARGET</varname></para> + </listitem> + + <listitem> + <para><varname>LDFLAGS</varname></para> + </listitem> + + <listitem> + <para><varname>LIBS</varname></para> + </listitem> + + <listitem> + <para><varname>MAKE_ARGS</varname></para> + </listitem> + + <listitem> + <para><varname>MAKE_ENV</varname></para> + </listitem> + + <listitem> + <para><varname>MASTER_SITES</varname></para> + </listitem> + + <listitem> + <para><varname>PATCHFILES</varname></para> + </listitem> + + <listitem> + <para><varname>PATCH_SITES</varname></para> + </listitem> + + <listitem> + <para><varname>PLIST_DIRS</varname></para> + </listitem> + + <listitem> + <para><varname>PLIST_FILES</varname></para> + </listitem> + + <listitem> + <para><varname>PLIST_SUB</varname></para> + </listitem> + + <listitem> + <para><varname>PORTDOCS</varname></para> + </listitem> + + <listitem> + <para><varname>PORTEXAMPLES</varname></para> + </listitem> + + <listitem> + <para><varname>SUB_FILES</varname></para> + </listitem> + + <listitem> + <para><varname>SUB_LIST</varname></para> + </listitem> + + <listitem> + <para><varname>TEST_TARGET</varname></para> + </listitem> + + <listitem> + <para><varname>USES</varname></para> + </listitem> + </itemizedlist> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, o valor da variável <varname><replaceable>OPT</replaceable>_<replaceable>ABOVEVARIABLE</replaceable></varname>, se definido, é anexado a <literal><replaceable>ABOVEVARIABLE</replaceable></literal>. <varname><replaceable>OPT</replaceable>_<replaceable>ABOVEVARIABLE</replaceable>_OFF</varname> funciona da mesma maneira, quando <literal>OPT</literal> <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_USES= gmake +OPT1_CFLAGS_OFF= -DTEST</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +USES+= gmake +.else +CFLAGS+= -DTEST +.endif</programlisting> + + <note> + <para>Algumas variáveis não estão nesta lista, em particular <varname>PKGNAMEPREFIX</varname> e <varname>PKGNAMESUFFIX</varname>. Isso é intencional. Um port <emphasis>não deve</emphasis> mudar seu nome quando alguma de suas opções forem alteradas.</para> + </note> + + <warning> + <para>Algumas dessas variáveis, pelo menos <varname>ALL_TARGET</varname>, <varname>DISTFILES</varname> e <varname>INSTALL_TARGET</varname>, tem seus valores padrão definidos <emphasis>depois</emphasis> das opções serem processadas.</para> + + <para>Com estas linhas no <filename>Makefile</filename>: </para> + + <programlisting>ALL_TARGET= all + +DOCS_ALL_TARGET= doc</programlisting> + + <para>Se a opção <literal>DOCS</literal> estiver ativada, <varname>ALL_TARGET</varname> terá o valor <literal>all doc</literal>; se a opção estiver desativada, ela terá o valor <literal>all</literal>.</para> + + <para>Com apenas a linha do assistente de opções no <filename>Makefile</filename>:</para> + + <programlisting>DOCS_ALL_TARGET= doc</programlisting> + + <para>Se a opção <literal>DOCS</literal> estiver ativada, <varname>ALL_TARGET</varname> terá o valor <literal>doc</literal>; se a opção estiver desativada, ela terá o valor <literal>all</literal>.</para> + </warning> + + </sect3> + + <sect3 xml:id="options-targets"> + <title>Targets Adicionais de Compilação, <buildtarget><replaceable>target</replaceable>-<replaceable>OPT</replaceable>-on</buildtarget> e <buildtarget><replaceable>target</replaceable>-<replaceable>OPT</replaceable>-off</buildtarget></title> + + <para>Estes targets de <filename>Makefile</filename> podem aceitar targets extras de compilação:</para> + + <itemizedlist> + <listitem> + <para><buildtarget>pre-fetch</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>do-fetch</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>post-fetch</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>pre-extract</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>do-extract</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>post-extract</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>pre-patch</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>do-patch</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>post-patch</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>pre-configure</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>do-configure</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>post-configure</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>pre-build</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>do-build</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>post-build</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>pre-install</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>do-install</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>post-install</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>post-stage</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>pre-package</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>do-package</buildtarget></para> + </listitem> + + <listitem> + <para><buildtarget>post-package</buildtarget></para> + </listitem> + </itemizedlist> + + <para>Quando a opção <replaceable>OPT</replaceable> é selecionada, o target <buildtarget><replaceable>TARGET</replaceable>-<replaceable>OPT</replaceable>-on</buildtarget>, se definido, é executado após <buildtarget><replaceable>TARGET</replaceable></buildtarget>. <buildtarget><replaceable>TARGET</replaceable>-<replaceable>OPT</replaceable>-off</buildtarget> funciona da mesma maneira, quando <literal>OPT</literal> <emphasis>não for</emphasis> selecionada. Por exemplo:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +post-patch: + @${REINPLACE_CMD} -e 's/echo/true/' ${WRKSRC}/Makefile + +post-patch-OPT1-on: + @${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile + +post-patch-OPT1-off: + @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${LOCALBASE}/bin/|' ${WRKSRC}/Makefile</programlisting> + + <para>é equivalente a:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +post-patch: + @${REINPLACE_CMD} -e 's/echo/true/' ${WRKSRC}/Makefile +.if ${PORT_OPTIONS:MOPT1} + @${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile +.else + @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${LOCALBASE}/bin/|' ${WRKSRC}/Makefile +.endif</programlisting> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="makefile-wrkdir"> + <title>Especificando o Diretório de Trabalho</title> + + <para>Cada port é extraído em um diretório de trabalho, que deve ter permissão de escrita. O sistema de ports tem por padrão os <varname>DISTFILES</varname> descompactado em um diretório chamado <literal>${DISTNAME}</literal>. Em outras palavras, se o <filename>Makefile</filename> tem:</para> + + <programlisting>PORTNAME= foo +DISTVERSION= 1.0</programlisting> + + <para>então os arquivos de distribuição do port contêm um diretório de nível superior, <filename>foo-1.0</filename>, e o resto dos arquivos estão localizados nesse diretório. </para> + + <para>Diversas variáveis podem ser substituídas se não for esse o caso.</para> + + <sect2 xml:id="makefile-wrksrc"> + <title><varname>WRKSRC</varname></title> + + <para>A variável lista o nome do diretório que é criado quando os distfiles do aplicativo são extraídos. Se o exemplo anterior for extraído em um diretório chamado <filename>foo</filename> (e não <filename>foo-1.0</filename>) escreva:</para> + + <programlisting>WRKSRC= ${WRKDIR}/foo</programlisting> + + <para>ou possivelmente</para> + + <programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting> + </sect2> + + <sect2 xml:id="makefile-wrksrc_subdir"> + <title><varname>WRKSRC_SUBDIR</varname></title> + + <para>Se o código fonte necessário para o port estiver em um subdiretório do arquivo de distribuição extraído, defina <varname>WRKSRC_SUBDIR</varname> para esse diretório.</para> + + <programlisting>WRKSRC_SUBDIR= src</programlisting> + </sect2> + + <sect2 xml:id="makefile-no_wrksubdir"> + <title><varname>NO_WRKSUBDIR</varname></title> + + <para>Se o port não extrair para nenhum subdiretório, então configure <varname>NO_WRKSUBDIR</varname> para indicar isso.</para> + + <programlisting>NO_WRKSUBDIR= yes</programlisting> + + <note> + <para>Porque <varname>WRKDIR</varname> é o único diretório que deve ter permissão de escrita durante a compilação e é usado para armazenar muitos arquivos que registram o status da compilação, a extração do port será forçada para um subdiretório.</para> + </note> + </sect2> + </sect1> + + <sect1 xml:id="conflicts"> + <title>Manipulando Conflitos</title> + + <para>Existem três variáveis diferentes para registrar um conflito entre pacotes e ports: <varname>CONFLICTS</varname>, <varname>CONFLICTS_INSTALL</varname> e <varname>CONFLICTS_BUILD</varname>.</para> + + <note> + <para>As variáveis de conflito definem automaticamente a variável <varname>IGNORE</varname>, que é mais amplamente documentada em <xref linkend="dads-noinstall"/>.</para> + </note> + + <para>Ao remover um dos vários ports conflitados, é aconselhável reter <varname>CONFLICTS</varname> nos outros ports por alguns meses para atender usuários que apenas fazem atualizações de vez em quando. </para> + + <variablelist xml:id="conflicts-variables"> + <varlistentry xml:id="conclicts-conflicts_install"> + <term><varname>CONFLICTS_INSTALL</varname></term> + + <listitem> <para>Se o pacote não puder coexistir com outros pacotes (devido a conflitos de arquivos, incompatibilidades de tempo de execução, etc.). A checagem <varname>CONFLICTS_INSTALL</varname> é feita após o estágio de compilação e antes do estágio de instalação.</para> + </listitem> </varlistentry> + + <varlistentry xml:id="conclicts-conflicts_build"> + <term><varname>CONFLICTS_BUILD</varname></term> + + <listitem> + <para>Se o port não puder ser compilado quando outros ports específicos já estiverem instalados. Conflitos de compilação não serão registrados no pacote final.</para> + </listitem> + + </varlistentry> + + <varlistentry xml:id="conclicts-conflicts"> + <term><varname>CONFLICTS</varname></term> + + <listitem> + <para>Se o port não puder ser compilado quando um certo port estiver instalado e o pacote final não puder coexistir com o outro pacote. A checagem <varname>CONFLICTS</varname> é feita antes do estágio de compilação e antes do estágio de instalação. </para> + </listitem> + </varlistentry> + </variablelist> + + <para>O conteúdo mais comum de uma dessas variáveis é o pacote base de outro port. O pacote base é o nome do pacote sem a versão, ele pode ser obtido executando <command>make -V PKGBASE</command>.</para> + + <example xml:id="conflicts-ex1"> + <title>Uso básico de <varname>CONFLICTS<replaceable>*</replaceable></varname></title> + + <para><package role="port">dns/bind99</package> não pode ser instalado se <package role="port">dns/bind910</package> está presente porque eles instalam os mesmos arquivos. Primeiro, reúna o pacote base para usar:</para> + + <screen><prompt>%</prompt> <userinput>make -C dns/bind99 -V PKGBASE</userinput> +bind99 +<prompt>%</prompt> <userinput>make -C dns/bind910 -V PKGBASE</userinput> +bind910</screen> + + <para>Então adicione ao <filename>Makefile</filename> do <package role="port">dns/bind99</package>: </para> + + <programlisting>CONFLICTS_INSTALL= bind910</programlisting> + + <para>E adicione ao <filename>Makefile</filename> do <package role="port">dns/bind910</package>:</para> + + <programlisting>CONFLICTS_INSTALL= bind99</programlisting> + </example> + + <para>Às vezes, apenas uma versão de outro port é incompatível, neste caso, use o nome completo do pacote, com a versão, e use shell globs, como <literal>*</literal> e <literal>?</literal> para garantir que todas as versões possíveis sejam correspondidas.</para> + + <example xml:id="conflicts-ex2"> + <title>Usando <varname>CONFLICTS<replaceable>*</replaceable></varname> Com Globs.</title> + + <para>Nas versões 2.0 até 2.4.1_2, <package role="port">deskutils/gnotime</package> instalava uma versão integrada de <package role="port">databases/qof</package>.</para> + + <para>Para refletir este passado, o <filename>Makefile</filename> do <package role="port">database/qof</package> contém:</para> + + <programlisting>CONFLICTS_INSTALL= gnotime-2.[0-3]* \ + gnotime-2.4.0* gnotime-2.4.1 \ + gnotime-2.4.1_[12]</programlisting> + + <para>As primeira entrada corresponde as versões <literal>2.0</literal> até <literal>2.3</literal>, a segunda corresponde todas as revisões de <literal>2.4.0</literal>, a terceira corresponde a versão exata <literal>2.4.1</literal>, e a última corresponde a primeira e segunda revisão da versão <literal>2.4.1</literal>.</para> + + <para><package role="port">deskutils/gnotime</package> não possui nenhuma linha de conflitos porque sua versão atual não conflita com mais nada.</para> + </example> + </sect1> + + <sect1 xml:id="install"> + <title>Instalando Arquivos</title> + + <important> + <para>O estágio <buildtarget>install</buildtarget> é muito importante para o usuário final porque ele adiciona arquivos ao sistema. Todos os comandos adicionais de estágios <buildtarget>*-install</buildtarget> dos <filename>Makefile</filename>'s de port devem ser mostrados na tela. <emphasis>Não</emphasis> silencie esses comandos com <literal>@</literal> ou <literal>.SILENT</literal>.</para> + </important> + + <sect2 xml:id="install-macros"> + <title>Macros <varname>INSTALL_<replaceable>*</replaceable></varname></title> + + <para>Use as macros fornecidas em <filename>bsd.port.mk</filename> para garantir a propriedade correta dos arquivos nos targets <buildtarget>*-install</buildtarget> do port. Defina a propriedade diretamente em <filename>pkg-plist</filename> com as entradas correspondentes, como <literal>@(<replaceable>owner</replaceable>,<replaceable>group</replaceable>,)</literal>, <literal>@owner <replaceable>owner</replaceable></literal>, e <literal>@group <replaceable>group</replaceable></literal>. Esses operadores funcionam até serem substituídos, ou até o final do <filename>pkg-plist</filename>, lembre-se de redefini-los depois que eles não forem mais necessários. O valor de propriedade padrão é <literal>root:wheel</literal>. Veja <xref linkend="plist-keywords-base"/> para maiores informações.</para> + + <itemizedlist> + <listitem> + <para><varname>INSTALL_PROGRAM</varname> é um comando para instalar executáveis binários.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_SCRIPT</varname> é um comando para instalar scripts executáveis.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_LIB</varname> é um comando para instalar bibliotecas compartilhadas (mas não bibliotecas estáticas).</para> + </listitem> + + <listitem> + <para><varname>INSTALL_KLD</varname> é um comando para instalar módulos carregáveis do kernel. Algumas arquiteturas não gostam de ter os módulos otimizados (stripped), então use este comando em vez de <varname>INSTALL_PROGRAM</varname>.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_DATA</varname> é um comando para instalar dados compartilháveis, incluindo bibliotecas estáticas.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_MAN</varname> é um comando para instalar manpages e outras documentações (ele não realiza nenhuma compactação).</para> + </listitem> + </itemizedlist> + + <para>Estas variáveis parametrizam o comando <citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> com as flags apropriadas para cada situação.</para> + + <important> + <para>Não use <varname>INSTALL_LIB</varname> para instalar bibliotecas estáticas, porque otimiza-las (strip) torna-as sem utilidade. Use <varname>INSTALL_DATA</varname> neste caso.</para> + </important> + </sect2> + + <sect2 xml:id="install-strip"> + <title>Otimizando (Stripping) Binários e Bibliotecas Compartilhadas</title> + + <para>Os binários instalados devem ser otimizados (stripped). Não otimize (strip) os binários manualmente, a menos que seja absolutamente necessário. A macro <varname>INSTALL_PROGRAM</varname> instala e otimiza (strip) o binário ao mesmo tempo. A macro <varname>INSTALL_LIB</varname> faz o mesmo com as bibliotecas compartilhadas.</para> + + <para>Quando um arquivo deve ser otimizado (stripped), mas as macros <varname>INSTALL_PROGRAM</varname> e <varname>INSTALL_LIB</varname> não são desejadas, <literal>${STRIP_CMD}</literal> otimiza (strips) o programa ou a biblioteca compartilhada. Isso geralmente é feito no target <buildtarget>post-install</buildtarget>. Por exemplo:</para> + + <programlisting>post-install: + ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl</programlisting> + + <para>Quando vários arquivos precisam ser otimizados (stripped):</para> + + <programlisting>post-install: +.for l in geometry media body track world + ${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0 +.endfor</programlisting> + + <para>Use <citerefentry><refentrytitle>file</refentrytitle><manvolnum>1</manvolnum></citerefentry> em um arquivo para determinar se ele foi otimizado (stripped). Binários são relatados por <citerefentry><refentrytitle>file</refentrytitle><manvolnum>1</manvolnum></citerefentry> como <literal>stripped</literal> ou <literal>not stripped</literal>. Além disso,<citerefentry><refentrytitle>strip</refentrytitle><manvolnum>1</manvolnum></citerefentry> irá detectar programas que já foram otimizados (stripped) e retornar o comando sem erros.</para> + + <important> + <para>Quando <varname>WITH_DEBUG</varname> estiver definido, os arquivos elf <emphasis>não devem</emphasis> ser otimizados (stripped).</para> + + <para>As variáveis (<varname>STRIP_CMD</varname>, <varname>INSTALL_PROGRAM</varname>, <varname>INSTALL_LIB</varname>, ...) e <link linkend="uses"><varname>USES</varname></link> fornecidas pelo framework lidam com isso automaticamente.</para> + + <para>Alguns softwares, adicionam <literal>-s</literal> em seus <varname>LDFLAGS</varname>, neste caso, ou remova o <literal>-s</literal> se <varname>WITH_DEBUG</varname> estiver definido, ou remova o incondicionalmente e use <varname>STRIP_CMD</varname> em <buildtarget>post-install</buildtarget>.</para> + </important> + </sect2> + + <sect2 xml:id="install-copytree"> + <title>Instalando uma Árvore Inteira de Arquivos</title> + + <para>Às vezes, um grande número de arquivos devem ser instalados preservando sua organização hierárquica. Por exemplo, copiando de uma árvore de diretórios inteira do <varname>WRKSRC</varname> para um diretório de destino sob <varname>PREFIX</varname>. Observe que <varname>PREFIX</varname>, <varname>EXEMPLESDIR</varname>, <varname>DATADIR</varname> e outras variáveis de caminho sempre devem ser precedidas por <varname>STAGEDIR</varname> para respeitar o staging (ver <xref linkend="staging"/>).</para> + + <para>Existem duas macros para essa situação. A vantagem de usar essas macros em vez de <command>cp</command> é que elas garantem a propriedade e permissão adequada dos arquivos nos arquivos de destino. A primeira macro, <varname>COPYTREE_BIN</varname>, irá definir todos os arquivos instalados como sendo executáveis, sendo assim, adequado para instalações em <filename>PREFIX/bin</filename>. A segunda macro,<varname>COPYTREE_SHARE</varname>, não define permissões de execução nos arquivos e, portanto, é adequado para instalar arquivos sob o destino <filename>PREFIX/share</filename>.</para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} + (cd ${WRKSRC}/examples && ${COPYTREE_SHARE} .${STAGEDIR}${EXAMPLESDIR})</programlisting> + + <para>Este exemplo irá instalar o conteúdo do diretório <filename>exemples</filename> do distfile do fornecedor para o local de exemplos apropriado do port. </para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${DATADIR}/summer + (cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer)</programlisting> + + <para>E este exemplo irá instalar os dados dos meses de verão no subdiretório <filename>summer</filename> de um <filename>DATADIR</filename>.</para> + + <para>Argumentos <command>find</command> adicionais podem ser passados através do terceiro argumento para <varname>COPYTREE_<replaceable>*</replaceable></varname>. Por exemplo, para instalar todos os arquivos do primeiro exemplo, exceto Makefiles, é possível usar esses comandos. </para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} + (cd ${WRKSRC}/examples && \ + ${COPYTREE_SHARE} .${STAGEDIR}${EXAMPLESDIR} "! -name Makefile")</programlisting> + + <para>Essas macros não adicionam os arquivos instalados em <filename>pkg-plist</filename>. Eles devem ser adicionados manualmente. Para documentação opcional (<varname>PORTDOCS</varname>, veja <xref linkend="install-documentation"/>) e exemplos (<varname>PORTEXAMPLES</varname>), os prefixos <literal>%%PORTDOCS%%</literal> ou <literal>%%PORTEXAMPLES%%</literal> devem ser prefixados no <filename>pkg-plist</filename>.</para> + </sect2> + + <sect2 xml:id="install-documentation"> + <title>Instalar Documentação Adicional</title> + + <para>Se o software tiver alguma documentação diferente do manual padrão e páginas de informações úteis para o usuário, instale-os em <varname>DOCSDIR</varname>. Isso pode ser feito como no item anterior, no target <buildtarget>post-install</buildtarget>.</para> + + <para>Crie um novo diretório para o port. O nome do diretório é <varname>DOCSDIR</varname>. Isso geralmente é igual a <varname>PORTNAME</varname>. No entanto, se o usuário desejar que versões diferentes do port sejam instaladas ao mesmo tempo, <varname>PKGNAME</varname> pode ser usado.</para> + + <para>Já que apenas os arquivos listados no <filename>pkg-plist</filename> são instalados, é seguro sempre instalar documentações no <varname>STAGEDIR</varname> (veja <xref linkend="staging"/>). Por isso, blocos <literal>.if</literal> são necessários apenas quando os arquivos forem grandes o suficiente para causarem sobrecarga significativa de I/O.</para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${DOCSDIR} + ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR}</programlisting> + + <para>Por outro lado, se houver uma opção DOCS no port, instale a documentação em um taget <buildtarget>post-install-DOCS-on</buildtarget>. Esses targets são descritos em <xref linkend="options-targets"/>.</para> + + <para>Aqui estão algumas variáveis úteis e como elas são expandidas por padrão quando usadas no <filename>Makefile</filename>: </para> + + <itemizedlist> + <listitem> + <para><varname>DATADIR</varname> é expandido para <filename>PREFIX/share/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>DATADIR_REL</varname> é expandido para <filename>share/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>DOCSDIR</varname> é expandido para <filename>PREFIX/share/doc/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>DOCSDIR_REL</varname> é expandido para <filename>share/doc/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>EXEMPLESDIR</varname> é expandido para <filename>PREFIX/share/examples/PORTNAME</filename>. </para> + </listitem> + + <listitem> + <para><varname>EXAMPLESDIR_REL</varname> é expandido para <filename>share/examples/PORTNAME</filename>.</para> + </listitem> + </itemizedlist> + + <note> + <para>A opção <literal>DOCS</literal> controla apenas a documentação adicional instalada em <varname>DOCSDIR</varname>. Não se aplica a páginas de manual e páginas de informações padrão. Arquivos instalados em <varname>EXEMPLESDIR</varname> são controlados pela opção <literal>EXEMPLES</literal>.</para> + </note> + + <para>Essas variáveis são exportadas para <varname>PLIST_SUB</varname>. Quando possível, seus valores aparecerão como nomes de caminho relativos ao <filename>PREFIX</filename>. Isso é, por padrão <filename>share/doc/PORTNAME</filename> será substituído por <literal>%%DOCSDIR%%</literal> na lista de empacotamento e assim por diante. (Saiba mais sobre substituições <filename>pkg-plist</filename> <link linkend="plist-sub">aqui</link>.</para> + + <para>Todos os arquivos e diretórios de documentação instalados condicionalmente são incluídos no <filename>pkg-plist</filename> com o prefixo <literal>%%PORTDOCS%%</literal>, por exemplo:</para> + + <programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS +%%PORTDOCS%%%%DOCSDIR%%/CONTACT</programlisting> + + <para>Como uma alternativa para listar os arquivos de documentação em <filename>pkg-plist</filename>, um port pode definir a variável <varname>PORTDOCS</varname> com uma lista de nomes de arquivo e padrões shell glob para adicionar à lista de empacotamento final. Os nomes serão relativos a <varname>DOCSDIR</varname>. Portanto, um port que utiliza <varname>PORTDOCS</varname> e usa um local não padrão para sua documentação, deve definir <varname>DOCSDIR</varname> adequadamente. Se um diretório estiver listado em <varname>PORTDOCS</varname> ou ser correspondido por um padrão glob dessa variável, toda a sub árvore de arquivos e diretórios contidos serão registrados na lista final de empacotamento. Se a opção <literal>DOCS</literal> estiver desmarcada, os arquivos e diretórios listados em <varname>PORTDOCS</varname> não serão instalados ou adicionados à lista de empacotamento do port. A instalação da documentação em <varname>PORTDOCS</varname> como mostrado acima fica a cargo do port. Um exemplo típico de utilização <varname>PORTDOCS</varname>:</para> + + <programlisting>PORTDOCS= README.* ChangeLog docs/*</programlisting> + + <note> + <para>O equivalente de <varname>PORTDOCS</varname> para arquivos instalados em <varname>DATADIR</varname> e <varname>EXEMPLESDIR</varname> são <varname>PORTDATA</varname> e <varname>PORTEXAMPLES</varname>, respectivamente.</para> + + <para>O conteúdo de <filename>pkg-message</filename> é exibido na instalação. Veja <link linkend="porting-message">a seção sobre o uso do <filename>pkg-message</filename></link> para mais detalhes. <filename>pkg-message</filename> não precisa ser adicionado ao <filename>pkg-plist</filename>.</para> + </note> + </sect2> + + <sect2 xml:id="install-subdirs"> + <title>Subdiretórios Sob <varname>PREFIX</varname></title> + + <para>Tente deixar o port colocar os arquivos nos subdiretórios corretos de <varname>PREFIX</varname>. Alguns ports juntam tudo e colocam os arquivos em um subdiretório com o nome do port, o que é incorreto. Além disso, muitos ports colocam todos arquivos, exceto binários, arquivos header e páginas de manual, em um subdiretório de <filename>lib</filename>, o que não funciona bem com o paradigma BSD. Muitos dos arquivos devem ser movidos para um desses diretórios: <filename>etc</filename>(setup/arquivos de configuração), <filename>libexec</filename> (executáveis iniciados internamente), <filename>sbin</filename> (executáveis para super-usuários/gerentes), <filename>info</filename> (documentação para o navegador de informações) ou <filename>share</filename> (arquivos independentes de arquitetura). Veja <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> para detalhes; as regras que regem <filename>/usr</filename> praticamente se aplicam a <filename>/usr/local</filename> também. A exceção são os ports que lidam com <quote>notícias</quote> USENET. Eles podem usar <filename>PREFIX/news</filename> como um destino para seus arquivos.</para> + </sect2> + </sect1> + + <sect1 xml:id="binary-alias"> + <title>Use <varname>BINARY_ALIAS</varname> para Renomear Comandos Em Vez de Aplicar Patch na Compilação</title> + + <para>Quando <varname>BINARY_ALIAS</varname> é definido, ele criará links simbólicos dos comandos fornecidos, em um diretório que será prefixado para o <varname>PATH</varname>.</para> + + <para>Use-o para substituir comandos codificados na fase de compilação sem ter aplicar nenhum patch nos arquivos de compilação.</para> + + <example xml:id="binary-alias-ex1"> + <title>Usando <varname>BINARY_ALIAS</varname> para Deixar <command>gsed</command> Disponível como <command>sed</command></title> + + <para>Alguns ports esperam que o <command>sed</command> se comporte como o <application>GNU sed</application> e utilizam recursos que o <citerefentry><refentrytitle>sed</refentrytitle><manvolnum>1</manvolnum></citerefentry> não possui. <application>GNU sed</application> está disponível em <package role="port">textproc/gsed</package> no FreeBSD.</para> + + <para>Use <varname>BINARY_ALIAS</varname> para substituir <command>sed</command> com <command>gsed</command> durante a compilação:</para> + + <programlisting>BUILD_DEPENDS= gsed:textproc/gsed +... +BINARY_ALIAS= sed=gsed</programlisting> + </example> + + <example xml:id="binary-alias-ex2"> + <title>Usando <varname>BINARY_ALIAS</varname> Para Fornecer Aliases para Comandos <command>python3</command> Codificado</title> + + <para>Um port que possui uma referência codificada para <command>python3</command> em seus scripts de compilação precisará ter ele disponível no <varname>PATH</varname> em tempo de compilação. Use <varname>BINARY_ALIAS</varname> para criar um alias que aponte para o binário certo do Python 3:</para> + + <programlisting>USES= python:3.4+,build +... +BINARY_ALIAS= python3=${PYTHON_CMD}</programlisting> + + <para>Veja <xref linkend="using-python"/> para mais informações sobre <literal>USES=python</literal>.</para> + </example> + </sect1> +</chapter> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="special"> + + <title>Considerações Especiais</title> + + <para>Esta seção explica as coisas mais comuns a se considerar ao criar um port.</para> + + <sect1 xml:id="staging"> + <title>Staging</title> + + <para><filename>bsd.port.mk</filename> espera que os ports trabalhem com um <quote>stage directory</quote>. Isso significa que um port não deve instalar arquivos diretamente nos diretórios de destino regulares (isto é, sob o <varname>PREFIX</varname>, por exemplo), mas em um diretório separado a partir do qual o pacote será construído. Em muitos casos, isso não requer privilégios de root, tornando possível criar pacotes como um usuário não privilegiado. Com o staging, o port é compilado e instalado no diretório sde estágio, <varname>STAGEDIR</varname>. Um pacote é criado a partir do diretório de estágio e, em seguida, instalado no sistema. As ferramentas Automake referem-se a este conceito como <varname>DESTDIR</varname>, mas no FreeBSD, <varname>DESTDIR</varname> tem um significado diferente (veja <xref linkend="porting-prefix"/>).</para> + + <note> + <para>Nenhum port <emphasis>realmente</emphasis> precisa de root. Ele pode ser evitado principalmente usando <link linkend="uses-uidfix"><literal>USES=uidfix</literal></link>. Se o port ainda executa comandos como <citerefentry><refentrytitle>chown</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>chgrp</refentrytitle><manvolnum>1</manvolnum></citerefentry> ou força o proprietário ou grupo com <citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> então use <link linkend="uses-fakeroot"><literal>USES=fakeroot</literal></link> para enganar essas chamadas. Algumas modificações no <filename>Makefile</filename> do port serão necessárias.</para> + </note> + + <para>Os meta ports, ou ports que não instalam arquivos por si mesmos e apenas dependem de outros ports, devem evitar extrair desnecessariamente <citerefentry><refentrytitle>mtree</refentrytitle><manvolnum>8</manvolnum></citerefentry> para o diretório de estágio. Este é o layout básico do diretório do pacote, e estes diretórios vazios serão vistos como órfãos. Para prevenir extração do <citerefentry><refentrytitle>mtree</refentrytitle><manvolnum>8</manvolnum></citerefentry>, adicione esta linha:</para> + + <programlisting>NO_MTREE= yes</programlisting> + + <tip> + <para>Metaports devem usar <link linkend="uses-metaport"><literal>USES=metaport</literal></link>. Ele configura padrões para ports que não baixam, criam ou instalam nada.</para> + </tip> + + <para>Staging é ativado pré-fixando a variável <varname>STAGEDIR</varname> para caminhos usados nos targets <buildtarget>pre-install</buildtarget>, <buildtarget>do-install</buildtarget> e <buildtarget>post-install</buildtarget> (veja os exemplos no livro). Normalmente, isso inclui as variáveis <varname>PREFIX</varname>, <varname>ETCDIR</varname>, <varname>DATADIR</varname>, <varname>EXEMPLESDIR</varname>, <varname>MANPREFIX</varname>, <varname>DOCSDIR</varname>, e assim por diante. Os diretórios devem ser criados como parte do target <buildtarget>post-install</buildtarget>. Evite usar caminhos absolutos sempre que possível.</para> + + <tip> + <para>Ports que instalam módulos do kernel devem preceder a variável <varname>STAGEDIR</varname> em seus destinos, padrão <filename>/boot/modules</filename>.</para> + </tip> + + <sect2 xml:id="staging-symlink"> + <title>Lidando com Links Simbólicos</title> + + <para>Ao criar um link simbólico, há dois casos, tanto a origem quanto o destino estão dentro de <filename>${PREFIX}</filename>. Nesse caso, use <command>${RLN}</command>. No outro caso, se um ou ambos os caminhos estiverem fora de <filename>${PREFIX}</filename> use <command>${LN} -s</command> e apenas prefixe <filename>${STAGEDIR}</filename> para o caminho de destino.</para> + + <example xml:id="staging-ex1"> + <title>Criar Links Simbólicos Relativos, Dentro de <filename>${PREFIX}</filename></title> + + <para><command>${RLN}</command> usa o recurso simbólico relativo do <citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> que libera o mantenedor do port de computar o caminho relativo.</para> + + <programlisting>${RLN} ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting> + + <para>Irá gerar:</para> + + <screen><prompt>%</prompt> <userinput>ls -lF ${STAGEDIR}${PREFIX}/lib</userinput> + lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 libfoo.so@ -> libfoo.so.42 + -rwxr-xr-x 1 nobody nobody 15 Aug 3 11:24 libfoo.so.42*</screen> + + <para>Quando usado com caminhos que não estão no mesmo diretório:</para> + + <programlisting>${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/<replaceable>bar</replaceable> ${STAGEDIR}${PREFIX}/bin/<replaceable>bar</replaceable></programlisting> + + <para>Irá gerar automaticamente os links simbólicos relativos:</para> + + <screen><prompt>%</prompt> <userinput>ls -lF ${STAGEDIR}${PREFIX}/bin</userinput> + lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar</screen> + </example> + + <example xml:id="staging-ex2"> + <title>Criar Links Simbólicos Absolutos, Fora de <filename>${PREFIX}</filename></title> + + <para>Ao criar um link simbólico fora de <filename>${PREFIX}</filename>, a origem não deve conter <filename>${STAGEDIR}</filename>, o destino no entanto, deve:</para> + + <programlisting>${LN} -sf <replaceable>/var/cache/${PORTNAME}</replaceable> ${STAGEDIR}${PREFIX}/share/<replaceable>${PORTNAME}</replaceable></programlisting> + + <para>Irá gerar:</para> + + <screen><prompt>%</prompt> <userinput>ls -lF ${STAGEDIRDIR}${PREFIX}/share</userinput> + lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 foo@ -> /var/cache/foo</screen> + </example> + </sect2> + </sect1> + + <sect1 xml:id="bundled-libs"> + <title>Bibliotecas Empacotadas (Bundled)</title> + + <para>Esta seção explica porque as dependências agrupadas(bundled) são consideradas ruins e o que fazer com elas.</para> + + <sect2 xml:id="bundled-libs-why-bad"> + <title>Por Que as Bibliotecas Agrupadas(Bundled) São Ruins</title> + + <para>Alguns softwares requerem que o mantenedor do port localize bibliotecas de terceiros e adicione as dependências necessárias ao port. Outros softwares agrupam todas as bibliotecas necessárias no arquivo de distribuição. A segunda abordagem parece mais fácil no começo, mas há algumas desvantagens sérias:</para> + + <para>Esta lista é vagamente baseada nas wikis <link xlink:href="https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries">Fedora</link> e <link xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link>, ambas licenciadas sob <link xlink:href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA 3.0</link>.</para> + + <variablelist> + <varlistentry> + <term>Segurança </term> + + <listitem> + <para>Se vulnerabilidades forem encontradas na biblioteca e arrumadas no upstream, elas podem não ser consertadas na biblioteca empacotada com o port. Uma razão pode ser que o autor não esteja ciente do problema. Isto significa que o mantenedor do port deve consertá-las, ou atualizar para uma versão não vulnerável e enviar um patch para o autor. Isso tudo leva tempo, o que resulta em software vulnerável por mais tempo do que o necessário. Isso, por sua vez, torna mais difícil coordenar uma correção sem vazamento desnecessário de informações sobre a vulnerabilidade.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Bugs</term> + + <listitem> + <para>Esse problema é semelhante ao problema de segurança no último parágrafo, mas geralmente menos grave.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Forking</term> + + <listitem> + <para>É mais fácil para o autor criar um fork da biblioteca depois que ela é empacotada. Embora seja conveniente à primeira vista, isso significa que o código diverge do upstream, dificultando o tratamento da segurança ou outros problemas com o software. A razão para isso é que o patching se torna mais difícil.</para> + + <para>Outro problema de forking é que, como o código diverge do upstream, os bugs são resolvidos repetidamente em vez de apenas uma vez em um local central. Isso, em primeiro lugar, anula a ideia de software de código aberto.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Colisão de símbolo</term> + + <listitem> + <para>Quando uma biblioteca é instalada no sistema, ela pode colidir com a versão empacotada. Isso pode causar erros imediatos no tempo de compilação ou link. Também pode causar erros ao executar o programa, o que pode ser mais difícil de rastrear. O último problema poderia ser causado porque as versões das duas bibliotecas são incompatíveis.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Licenciamento</term> + + <listitem> + <para>Ao agrupar projetos de diferentes fontes, os problemas de licença podem surgir com mais facilidade, especialmente quando as licenças são incompatíveis. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Desperdício de recursos</term> + + <listitem> + <para>Bibliotecas empacotadas desperdiçam recursos em vários níveis. Demora mais para compilar o aplicativo real, especialmente se essas bibliotecas já estiverem presentes no sistema. Em tempo de execução, elas podem ocupar memória desnecessária quando a biblioteca do sistema já está carregada por um programa e a biblioteca agrupada é carregada por outro programa. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Desperdício de esforço</term> + + <listitem> + <para>Quando uma biblioteca precisa de patches para o FreeBSD, esses patches precisam ser duplicados novamente na biblioteca. Isso desperdiça tempo do desenvolvedor porque os patches podem não ser aplicados de forma limpa. Também pode ser difícil perceber que estes patches são necessários em primeiro lugar.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 xml:id="bundled-libs-practices"> + <title>O Que Fazer em Relação às Bibliotecas Agrupadas</title> + + <para>Sempre que possível, use a versão separada da biblioteca adicionando um <varname>LIB_DEPENDS</varname> para o port. Se esse port ainda não existir, considere criá-lo.</para> + + <para>Use bibliotecas agrupadas somente se o upstream tiver um bom histórico de segurança e se o uso de versões não agrupadas originarem patches excessivamente complexos</para> + + <note> + <para>Em alguns casos muito especiais, por exemplo, emuladores, como o <application>Wine</application>, um port tem que agrupar bibliotecas, porque elas estão em uma arquitetura diferente ou foram modificadas para se adequarem ao uso do software. Nesse caso, essas bibliotecas não devem ser expostas a outros ports para vinculação. Adicione <literal>BUNDLE_LIBS=yes</literal> no <filename>Makefile</filename> do port. Isso vai dizer ao <citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>8</manvolnum></citerefentry> para não computar as bibliotecas fornecidas. Pergunte sempre à equipe de gerenciamento do ports <email>portmgr@FreeBSD.org</email> antes de adicionar isso a um port.</para> + </note> + </sect2> + </sect1> + + <sect1 xml:id="porting-shlibs"> + <title>Bibliotecas Compartilhadas</title> + + <para>Se o port instalar uma ou mais bibliotecas compartilhadas, defina a variável <varname>USE_LDCONFIG</varname> para o make , a qual irá instruir o <filename>bsd.port.mk</filename> para executar o <literal>${LDCONFIG} -m</literal> no diretório onde a nova biblioteca está instalada (geralmente em <filename>PREFIX/lib</filename>) durante o target <buildtarget>post-install</buildtarget> para registrá-la no cache da biblioteca compartilhada. Esta variável, quando definida, também facilitará a adição do par <literal>@exec /sbin/ldconfig -m</literal> e <literal>@unexec /sbin/ldconfig -R</literal> no <filename>pkg-plist</filename>, para que o usuário que instalou o pacote possa começar a usar a biblioteca compartilhada imediatamente e para que a desinstalação não faça com que o sistema acredite que a biblioteca ainda está lá.</para> + + <programlisting>USE_LDCONFIG= yes</programlisting> + + <para>O diretório padrão pode ser substituído configurando a variável <varname>USE_LDCONFIG</varname> para uma lista de diretórios nos quais as bibliotecas compartilhadas devem ser instaladas. Por exemplo, se o port instalar bibliotecas compartilhadas em <filename>PREFIX/lib/foo</filename> e <filename>PREFIXO/lib/bar</filename> utilize isso no <filename>Makefile</filename>: </para> + + <programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting> + + <para>Por favor, verifique novamente, muitas vezes isso não é necessário ou é algo que pode ser evitado através do uso da opção <literal>-rpath</literal> ou da configuração da variável <envar>LD_RUN_PATH</envar> durante a fase de vinculação (consulte <package role="port">lang/mosml</package> para um exemplo), ou através de um shell-wrapper que defina o <varname>LD_LIBRARY_PATH</varname> antes de executar o binário, como por exemplo o <package role="port">www/seamonkey</package> faz.</para> + + <para>Ao instalar bibliotecas de 32 bits em um sistema de 64 bits, use <varname>USE_LDCONFIG32</varname> como alternativa.</para> + + <para>Se o software usa o <link linkend="using-autotools">autotools</link>, e especificamente, o <command>libtool</command>, adicione <link linkend="uses-libtool"><literal>USES=libtool</literal></link></para> + + <para>Quando o número da versão da biblioteca principal aumenta na atualização para a nova versão do port, todos os outros ports que se vinculam à biblioteca afetada devem ter seu <varname>PORTREVISION</varname> incrementado, para forçar a recompilação com a nova versão da biblioteca. </para> + </sect1> + + <sect1 xml:id="porting-restrictions"> + <title>Ports com Restrições de Distribuição ou Preocupações Legais</title> + + <para>As licenças variam e algumas delas impõem restrições sobre como o aplicativo pode ser empacotado, se pode ser vendido com fins lucrativos e assim por diante.</para> + + <important> + <para>É de responsabilidade de um mantenedor de um port ler os termos de licenciamento do software e certificar-se de que o projeto do FreeBSD não será responsabilizado por violá-los, redistribuindo o código fonte ou os binários compilados via FTP/HTTP ou CD-ROM. Se estiver em dúvida, entre em contato com a <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">Lista de discussão de ports do FreeBSD</link></para> + </important> + + <para>Em situações como esta, as variáveis descritas nas próximas seções podem ser definidas.</para> + + <sect2 xml:id="porting-restrictions-no_package"> + <title><varname>NO_PACKAGE</varname></title> + + <para>Esta variável indica que não podemos gerar um pacote binário da aplicação. Por exemplo, a licença pode proibir a redistribuição binária, ou pode proibir a distribuição de pacotes criados a partir de código adaptado.</para> + + <para>No entanto, o <varname>DISTFILES</varname> do port pode ser livremente espelhado no FTP/HTTP. Eles também podem ser distribuídos em um CD-ROM (ou mídia similar), a menos que a variável <varname>NO_CDROM</varname> esteja definida também. </para> + + <para>Se o pacote binário geralmente não é útil, e o aplicativo sempre deve ser compilado a partir do código-fonte, use o <varname>NO_PACKAGE</varname>. Por exemplo, se o aplicativo tiver informações de configuração específicas do site codificadas nele em tempo de compilação, defina o <varname>NO_PACKAGE</varname></para> + + <para>Defina a variável <varname>NO_PACKAGE</varname> para uma string descrevendo o motivo pelo qual o pacote não pode ser gerado. </para> + </sect2> + + <sect2 xml:id="porting-restrictions-no_cdrom"> + <title><varname>NO_CDROM</varname></title> + + <para>Esta variável sozinha indica que, embora tenhamos permissão para gerar pacotes binários, não podemos colocar nem esses pacotes nem o <varname>DISTFILES</varname> em um CD-ROM (ou mídia similar) para revenda. No entanto, os pacotes binários e os <varname>DISTFILES</varname> do ports ainda estarão disponíveis via FTP/HTTP. </para> + + <para>Se esta variável for definida junto com <varname>NO_PACKAGE</varname>, então apenas o <varname>DISTFILES</varname> do port estará disponível e somente via FTP/HTTP. </para> + + <para>Defina a variável <varname>NO_CDROM</varname> para uma string descrevendo o motivo pelo qual o port não pode ser redistribuído em CD-ROM. Por exemplo, use isto se a licença do port for somente para uso <quote>não comercial</quote>.</para> + </sect2> + + <sect2 xml:id="porting-restrictions-nofetchfiles"> + <title><varname>NOFETCHFILES</varname></title> + + <para>Arquivos definidos em <varname>NOFETCHFILES</varname> não podem ser obtidos de nenhum dos <varname>MASTER_SITES</varname>. Um exemplo de tal tipo de arquivo é quando o arquivo é fornecido apenas em CD-ROM pelo fornecedor. </para> + + <para>Ferramentas que verificam a disponibilidade desses arquivos nos <varname>MASTER_SITES</varname> devem ignorar estes arquivos e não informar nada sobre eles.</para> + </sect2> + + <sect2 xml:id="porting-restrictions-restricted"> + <title><varname>RESTRICTED</varname></title> + + <para>Defina esta variável sozinha, se a licença do aplicativo não permitir o espelhamento do <varname>DISTFILES</varname> e nem a distribuição do pacote binário de forma alguma.</para> + + <para>Não defina as variáveis <varname>NO_CDROM</varname> ou <varname>NO_PACKAGE</varname> juntamente com a variável <varname>RESTRICT</varname>, uma vez que esta última variável implica as anteriores.</para> + + <para>Defina a variável <varname>RESTRICTED</varname> para uma string que descreva o motivo pelo qual o port não pode ser redistribuído. Normalmente, isso indica que o port contém software proprietário e que o usuário precisará baixar manualmente o <varname>DISTFILES</varname>, possivelmente após se registrar para ter acesso ao software ou após concordar em aceitar os termos de um <acronym>EULA</acronym>.</para> + </sect2> + + <sect2 xml:id="porting-restrictions-restricted_files"> + <title><varname>RESTRICTED_FILES</varname></title> + + <para>Quando a variável <varname>RESTRICT</varname> ou a <varname>NO_CDROM</varname> está definida, o valor padrão normalmente contém <literal>${DISTFILES}${PATCHFILES}</literal> caso contrário, ela fica vazia. Se apenas alguns dos arquivos da distribuição forem restritos, defina essa variável para listá-los. </para> + + </sect2> + + <sect2 xml:id="porting-restrictions-legal_text"> + <title><varname>LEGAL_TEXT</varname></title> + + <para>Se o port tem preocupações legais as quais não foram abordadas pelas variáveis acima, defina a variável <varname>LEGAL_TEXT</varname> para uma string explicando a preocupação. Por exemplo, se o FreeBSD obteve uma permissão especial para redistribuir o binário, esta variável deve indicar isso. </para> + </sect2> + + <sect2 xml:id="porting-restrictions-legal"> + <title><filename>/usr/ports/LEGAL</filename> e <varname>LEGAL</varname></title> + + <para>Um port que defina qualquer uma das variáveis acima também deverá ser adicionado ao <filename>/usr/ports/LEGAL</filename>. A primeira coluna é uma glob que corresponde aos distfiles restritos. A segunda coluna é a origem do port. A terceira coluna é a saída do comando <command>make -VLEGAL</command>.</para> + </sect2> + + <sect2 xml:id="porting-restrictions-examples"> + <title>Exemplos</title> + + <para>A maneira preferida de declarar "os distfiles para este port devem ser obtidos manualmente" é a seguinte:</para> + + <programlisting>.if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX}) +IGNORE= may not be redistributed because of licensing reasons. Please visit <replaceable>some-website</replaceable> to accept their license and download ${DISTFILES} into ${DISTDIR} +.endif</programlisting> + + <para>Isso tanto informa o usuário, quanto define os metadados apropriados na máquina do usuário para uso por programas automatizados.</para> + + <para>Note que esta estrofe deve ser precedida por uma inclusão de <filename>bsd.port.pre.mk</filename>.</para> + </sect2> + </sect1> + + <sect1 xml:id="building"> + <title>Mecanismos de Compilação</title> + + <sect2 xml:id="parallel-builds"> + <title>Compilando Ports em Paralelo</title> + + <para>O framework de ports do FreeBSD suporta compilação paralela usando múltiplos subprocessos do comando <command>make</command>, o que permite que os sistemas <acronym>SMP</acronym> utilizem todo o poder disponível da <acronym>CPU</acronym>, permitindo que as compilações dos ports sejam mais rápidas e eficazes. </para> + + <para>Isso é alcançado passando-se a flag <varname>-jX</varname> para o <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> executando no código do fornecedor. Este é o comportamento de compilação padrão dos ports. Infelizmente, nem todos os ports lidam bem com compilações paralelas e pode ser necessário desabilitar explicitamente esse recurso adicionando a variável <literal>MAKE_JOBS_UNSAFE=yes</literal>. Ela é usada quando um port é conhecido por não funcionar com a opção <varname>-jX</varname>.</para> + + <important> + <para>Ao definir a variável <varname>MAKE_JOBS_UNSAFE</varname>, é muito importante explicar com um comentário no <filename>Makefile</filename>, ou pelo menos na mensagem de commit, <emphasis>porque</emphasis> o port não pode ser compilado quando ela está ativa. Caso contrário, é quase impossível corrigir o problema ou testar se ele foi corrigido ao efetuar o commit de uma atualização em uma data posterior. </para> + </important> + </sect2> + + <sect2 xml:id="using-make"> + <title><command>make</command>, <command>gmake</command>, e <command>imake</command></title> + + <para>Existem várias implementações diferentes do <literal>make</literal>. O software portado geralmente requer uma implementação específica, como o <acronym>GNU</acronym> <command>make</command>, conhecido no FreeBSD como <command>gmake</command>.</para> + + <para>Se o port usa o <application>GNU make</application>, adicione o <literal>gmake</literal> no <literal>USES</literal>.</para> + + <para>A variável <varname>MAKE_CMD</varname> pode ser usada para referenciar o comando específico configurado pelo <literal>USES</literal> no <filename>Makefile</filename> do port. Use o <varname>MAKE_CMD</varname> apenas dentro dos <filename>Makefile</filename>s do aplicativo no <varname>WRKSRC</varname> para chamar o comando <command>make</command> para a implementação esperada pelo software portado.</para> + + <para>Se o port é um aplicativo X que usa o <application>Imake</application> para criar o <filename>Makefile</filename> do <filename>Imakefile</filename>, defina <literal>USES=imake</literal>. Veja a seção sobre <link linkend="uses-imake"><literal>USES=imake</literal></link> no <xref linkend="uses"/> para mais detalhes.</para> + + <para>Se o <filename>Makefile</filename> do port tem algo diferente de <buildtarget>all</buildtarget> como o target de compilação principal, defina a variável <varname>ALL_TARGET</varname> adequadamente. O mesmo vale para <buildtarget>install</buildtarget> e <varname>INSTALL_TARGET</varname>.</para> + </sect2> + + <sect2 xml:id="using-configure"> + <title>Script <command>configure</command></title> + + <para>Se o port usa o script <command>configure</command> para gerar <filename>Makefile</filename>s a partir do <filename>Makefile.in</filename> defina <literal>GNU_CONFIGURE=yes</literal>. Para dar argumentos extras ao script <command>configure</command> (o argumento padrão é <literal>--prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir = ${MANPREFIX}/man --build = ${CONFIGURE_TARGET}</literal>), defina estes argumentos extras em <varname>CONFIGURE_ARGS</varname>. Variáveis de ambiente extras podem ser passadas usando <varname>CONFIGURE_ENV</varname>.</para> + + <table frame="none" xml:id="using-configure-variables"> + <title>Variáveis para ports que usam o <command>configure</command></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Significa</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>GNU_CONFIGURE</varname></entry> + <entry>O port usa o script <command>configure</command> para preparar a construção. </entry> + </row> + + <row> + <entry><varname>HAS_CONFIGURE</varname></entry> + <entry>Igual a <varname>GNU_CONFIGURE</varname>, exceto que o destino de configuração padrão não é adicionado a <varname>CONFIGURE_ARGS</varname>.</entry> + </row> + + <row> + <entry><varname>CONFIGURE_ARGS</varname></entry> + <entry>Argumentos adicionais passados para o script <command>configure</command>.</entry> + </row> + + <row> + <entry><varname>CONFIGURE_ENV</varname></entry> + <entry>Variáveis de ambiente adicionais a serem definidas para execução de script <command>configure</command>. </entry> + </row> + + <row> + <entry><varname>CONFIGURE_TARGET</varname></entry> + <entry>Substitui o target de configuração padrão. O valor padrão é <literal>${MACHINE_ARCH}-portbld-freebsd${OSREL}</literal>.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2 xml:id="using-cmake"> + <title>Usando o <command>cmake</command></title> + + <para>Para ports que usam o <application>CMake</application>, defina <literal>USES=cmake</literal> ou <literal>USES=cmake:outsource</literal> para compilar em um diretório separado (veja abaixo).</para> + + <table frame="none" xml:id="using-cmake-variables"> + <title>Variáveis para ports que usam o <command>cmake</command></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Significa</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>CMAKE_ARGS</varname></entry> + <entry>Flags do <application>CMake</application> especificas para o port a serem passadas para o binário do <command>cmake</command>.</entry> + </row> + + <row> + <entry><varname>CMAKE_ON</varname></entry> + <entry>Para cada entrada em <varname>CMAKE_ON</varname>, um valor booleano ativado é adicionado ao <varname>CMAKE_ARGS</varname>. Veja <xref linkend="using-cmake-example2"/>.</entry> + </row> + + <row> + <entry><varname>CMAKE_OFF</varname></entry> + <entry>Para cada entrada em <varname>CMAKE_OFF</varname>, um valor booleano desativado é adicionado ao <varname>CMAKE_ARGS</varname>. Veja <xref linkend="using-cmake-example2"/>.</entry> + </row> + + <row> + <entry><varname>CMAKE_BUILD_TYPE</varname></entry> + <entry>Tipo de compilação (perfis de compilação predefinidos para o <application>CMake</application>). O padrão é <literal>Release</literal> ou <literal>Debug</literal> se a variável <varname>WITH_DEBUG</varname> estiver definida.</entry> + </row> + + <row> + <entry><varname>CMAKE_SOURCE_PATH</varname></entry> + <entry>Caminho para o diretório do fonte. O padrão é <literal>${WRKSRC}</literal>.</entry> + </row> + + <row> + <entry><varname>CONFIGURE_ENV</varname></entry> + <entry>Variáveis de ambiente adicionais a serem definidas para o binário do <command>cmake</command>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" xml:id="using-cmake-user-variables"> + <title>Variáveis que os usuários podem definir para compilações com <command>cmake</command></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Significa</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>CMAKE_VERBOSE</varname></entry> + <entry>Ativa o output detalhado da compilação. Não é definido por padrão, a menos que <varname>BATCH</varname> ou <varname>PACKAGE_BUILDING</varname> esteja definido.</entry> + </row> + + <row> + <entry><varname>CMAKE_NOCOLOR</varname></entry> + <entry>Desativa o output colorido na compilação. Não é definido por padrão, a menos que <varname>BATCH</varname> ou <varname>PACKAGE_BUILDING</varname> esteja definido.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para><application>CMake</application> suporta estes perfis de construção: <literal>Debug</literal>, <literal>Release</literal>, <literal>RelWithDebInfo</literal> e <literal>MinSizeRel</literal>. <literal>Debug</literal> e <literal>Release</literal> sistema de respeito de perfis <literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal> e <literal>MinSizeRel</literal> ajustará <varname>CFLAGS</varname> para <literal>-O2 -g</literal> e <literal>-Os -DNDEBUG</literal> correspondentemente. O valor do invólucro inferior <varname>CMAKE_BUILD_TYPE</varname> é exportado para <varname>PLIST_SUB</varname> e deve ser usado se o port for instalar <filename><replaceable>*</replaceable>.cmake</filename> dependendo do tipo de compilação (consulte<package role="port"> deskutils/strigi</package>Por exemplo). Por favor, note que alguns projetos podem definir seus próprios perfis de compilação e/ou forçar um tipo específico de compilação <literal>CMAKE_BUILD_TYPE</literal> dentro de <filename>CMakeLists.txt</filename>. Para fazer um port para tal projeto respeite <varname>CFLAGS</varname> e <varname>WITH_DEBUG</varname>, as definições <literal>CMAKE_BUILD_TYPE</literal> devem ser removidas desses arquivos.</para> + + <para>A maioria dos projetos baseados no <application>CMake</application> suportam um método de compilação fora da fonte. A compilação fora da fonte de um port pode ser solicitada usando o sufixo <literal>:outsource</literal>. Quando ativado, as variáveis <varname>CONFIGURE_WRKSRC</varname>, <varname>BUILD_WRKSRC</varname> e <varname>INSTALL_WRKSRC</varname> serão definidas para <literal>${WRKDIR}/.Build</literal> e esse diretório será usado para manter todos os arquivos gerados durante a configuração e os estágios de compilação, deixando o diretório de origem intacto. </para> + + <example xml:id="using-cmake-example"> + <title>Exemplo de <literal>USES=cmake</literal></title> + + <para>Este trecho demonstra o uso do <application>CMake</application> para um port. O <varname>CMAKE_SOURCE_PATH</varname> geralmente não é necessário, mas pode ser definido quando os fontes não estão localizados no diretório superior ou se apenas um subconjunto do projeto for compilado pelo port. </para> + + <programlisting>USES= cmake:outsource +CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> + </example> + + <example xml:id="using-cmake-example2"> + <title><varname>CMAKE_ON</varname> and <varname>CMAKE_OFF</varname></title> + + <para>Ao adicionar valores booleanos a variável <varname>CMAKE_ARGS</varname>, será mais fácil usar as variáveis <varname>CMAKE_ON</varname> e <varname>CMAKE_OFF</varname> em vez disso. Desta forma:</para> + + <programlisting>CMAKE_ON= VAR1 VAR2 +CMAKE_OFF= VAR3</programlisting> + + <para>É equivalente a:</para> + + <programlisting>CMAKE_ARGS= -DVAR1:BOOL=TRUE -DVAR2:BOOL=TRUE -DVAR3:BOOL=FALSE</programlisting> + + <important> + <para>Isto é apenas para os valores padrão desativados do <varname>CMAKE_ARGS</varname>. Os helpers descritos em <xref linkend="options-cmake_bool"/> usam a mesma semântica, mas para valores opcionais. </para> + </important> + </example> + </sect2> + + <sect2 xml:id="using-scons"> + <title>Usando <command>scons</command></title> + + <para>Se o port usa <application>SCons</application>, definir <literal>USES=scons</literal></para> + + <para>Para fazer os <filename>SConstruct</filename> de terceiros respeitarem tudo o que é passado para SCons no ambiente (isto é, o mais importante, <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), altere o <filename>SConstruct</filename> para que o <literal>Evironment</literal> de compilação fique da seguinte forma: </para> + + <programlisting>env = Environment(**ARGUMENTS)</programlisting> + + <para>Ele poderá então ser modificado com <literal>env.Append</literal> e <literal>env.Replace</literal></para> + </sect2> + + <sect2 xml:id="using-cargo"> + <title>Usando <command>cargo</command></title> + + <para>Para ports que usam <application>Cargo</application>, defina <literal>USES=cargo</literal></para> + + <table frame="none" xml:id="using-cargo-user-variables"> + <title>Variáveis que os Usuários Podem Configurar para Compilar <command>cargo</command></title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Variável</entry> + <entry>Padrão</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>CARGO_CRATES</varname></entry> + <entry/> + <entry>Lista de crates que o port depende. Cada entrada precisa ter um formato como <literal>cratename-semver</literal> por exemplo, <literal>libc-0.2.40</literal>. Os mantenedores de ports podem gerar essa lista a partir do <filename>Cargo.lock</filename> usando o comando <command>make cargo-crates</command>. É possível alterar manualmente as versões dos crates, mas tenha em mente as dependências transitivas.</entry> + </row> + + <row> + <entry><varname>CARGO_FEATURES</varname></entry> + <entry/> + <entry>Lista de recursos da aplicação para compilar (lista separada por espaço).</entry> + </row> + + <row> + <entry><varname>CARGO_CARGOTOML</varname></entry> + <entry><literal>${WRKSRC}/Cargo.toml</literal></entry> + <entry>O caminho para o <filename>Cargo.toml</filename> que será usado.</entry> + </row> + + <row> + <entry><varname>CARGO_CARGOLOCK</varname></entry> + <entry><literal>${WRKSRC}/Cargo.lock</literal></entry> + <entry>O caminho para o <filename>Cargo.lock</filename> que será utilizado para o <command>make cargo-crates</command>. É possível especificar mais de um arquivo de bloqueio quando necessário. </entry> + </row> + + <row> + <entry><varname>CARGO_ENV</varname></entry> + <entry/> + <entry>Uma lista de variáveis de ambiente para passar para o Cargo semelhante a <varname>MAKE_ENV</varname>.</entry> + </row> + + <row> + <entry><varname>RUSTFLAGS</varname></entry> + <entry/> + <entry>Flags para passar para o compilador Rust.</entry> + </row> + + <row> + <entry><varname>CARGO_CONFIGURE</varname></entry> + <entry><literal>yes</literal></entry> + <entry>Use o padrão <buildtarget>do-configure</buildtarget>.</entry> + </row> + + <row> + <entry><varname>CARGO_UPDATE_ARGS</varname></entry> + <entry/> + <entry>Argumentos extras para passar para o Cargo durante a fase de configuração. Os argumentos válidos podem ser consultados com <command>cargo update --help</command>.</entry> + </row> + + <row> + <entry><varname>CARGO_BUILDDEP</varname></entry> + <entry><literal>yes</literal></entry> + <entry>Adiciona uma dependência de compilação em <package role="port">lang/rust</package>.</entry> + </row> + + <row> + <entry><varname>CARGO_CARGO_BIN</varname></entry> + <entry><literal>${LOCALBASE}/bin/cargo</literal></entry> + <entry>Localização do binário do <command>cargo</command>.</entry> + </row> + + <row> + <entry><varname>CARGO_BUILD</varname></entry> + <entry><literal>yes</literal></entry> + <entry>Use o padrão <buildtarget>do-build</buildtarget>.</entry> + </row> + + <row> + <entry><varname>CARGO_BUILD_ARGS</varname></entry> + <entry/> + <entry>Argumentos extras para passar para o Cargo durante a fase de compilação. Argumentos válidos podem ser consultados com <command>cargo buil --help</command>.</entry> + </row> + + <row> + <entry><varname>CARGO_INSTALL</varname></entry> + <entry><literal>yes</literal></entry> + <entry>Use o padrão <buildtarget>do-install</buildtarget>.</entry> + </row> + + <row> + <entry><varname>CARGO_INSTALL_ARGS</varname></entry> + <entry/> + <entry>Argumentos extras para passar para o Cargo durante a fase de instalação. Os argumentos válidos podem ser consultados com <command>cargo isntall --help</command>.</entry> + </row> + + <row> + <entry><varname>CARGO_TEST</varname></entry> + <entry><literal>yes</literal></entry> + <entry>Use o padrão <buildtarget>do-test</buildtarget>.</entry> + </row> + + <row> + <entry><varname>CARGO_TEST_ARGS</varname></entry> + <entry/> + <entry>Argumentos extras para passar para o Cargo durante a fase de teste. Os argumentos válidos podem ser consultados com <command>cargo test --help</command>.</entry> + </row> + + <row> + <entry><varname>CARGO_TARGET_DIR</varname></entry> + <entry><literal>${WRKDIR}/target</literal></entry> + <entry>Localização do diretório de saída do cargo.</entry> + </row> + + <row> + <entry><varname>CARGO_DIST_SUBDIR</varname></entry> + <entry><filename>rust/crates</filename></entry> + <entry>Diretório relativo a <varname>DISTDIR</varname> onde os arquivos de distribuição do crate serão armazenados. </entry> + </row> + + <row> + <entry><varname>CARGO_VENDOR_DIR</varname></entry> + <entry><literal>${WRKSRC}/cargo-crates</literal></entry> + <entry>Localização do diretório do fornecedor onde todas os crates serão extraídos. Tente manter isto sob <varname>PATCH_WRKSRC</varname>, para que os patches possam ser aplicados facilmente.</entry> + </row> + + <row> + <entry><varname>CARGO_USE_GITHUB</varname></entry> + <entry><literal>no</literal></entry> + <entry>Ativa a busca de crates bloqueadas para commits específicos do Git no GitHub via <varname>GH_TUPLE</varname>. Isso tentará corrigir tanto o <filename>Cargo.lock</filename> quanto o <filename>Cargo.toml</filename> para apontar para os fontes off-line, em vez de buscá-los em um repositório Git durante a compilação. Use com cuidado, pois as dependências transitivas do Git não são resolvidas e corrigidas corretamente.</entry> + </row> + + <row> + <entry><varname>CARGO_GH_CARGOTOML</varname></entry> + <entry><literal>${CARGO_CARGOTOML}</literal></entry> + <entry>Lista do <filename>Cargo.toml</filename> que será corrigido quando ao utilizar o <varname>CARGO_USE_GITHUB</varname>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="cargo-ex1"> + <title>Criando um Port para uma Aplicação Simples em Rust</title> + + <para>Criar um port baseado em cargo é um processo de três estágios. Primeiro, precisamos fornecer um modelo de port que busque o arquivo de distribuição do aplicativo:</para> + + <programlisting>PORTNAME= tokei +DISTVERSIONPREFIX= v +DISTVERSION= 7.0.2 +CATEGORIES= devel + +MAINTAINER= tobik@FreeBSD.org +COMMENT= Display statistics about your code + +USES= cargo +USE_GITHUB= yes +GH_ACCOUNT= Aaronepower + +.include <bsd.port.mk></programlisting> + + <para>Gerar uma <filename>distinfo</filename> inicial:</para> + + <screen><prompt>%</prompt> <userinput>make makesum</userinput> +=> Aaronepower-tokei-v7.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. +=> Attempting to fetch https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz +fetch: https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz: size of remote file is not known +Aaronepower-tokei-v7.0.2_GH0.tar.gz 45 kB 239 kBps 00m00s</screen> + + <para>Agora o arquivo de distribuição está pronto para uso e podemos ir em frente e extrair as dependências crate do pacote <filename>Cargo.lock</filename>: </para> + + <screen><prompt>%</prompt> <userinput>make cargo-crates</userinput> +CARGO_CRATES= aho-corasick-0.6.4 \ + ansi_term-0.11.0 \ + arrayvec-0.4.7 \ + atty-0.2.9 \ + bitflags-1.0.1 \ + byteorder-1.2.2 \ + [...]</screen> + + <para>A saída deste comando precisa ser colada diretamente no Makefile:</para> + + <programlisting>PORTNAME= tokei +DISTVERSIONPREFIX= v +DISTVERSION= 7.0.2 +CATEGORIES= devel + +MAINTAINER= tobik@FreeBSD.org +COMMENT= Display statistics about your code + +USES= cargo +USE_GITHUB= yes +GH_ACCOUNT= Aaronepower + +CARGO_CRATES= aho-corasick-0.6.4 \ + ansi_term-0.11.0 \ + arrayvec-0.4.7 \ + atty-0.2.9 \ + bitflags-1.0.1 \ + byteorder-1.2.2 \ + [...] + +.include <bsd.port.mk></programlisting> + + <para>O <filename>distinfo</filename> precisa ser regenerado para conter todos os arquivos de distribuição dos crates:</para> + + <screen><prompt>%</prompt> <userinput>make makesum</userinput> +=> rust/crates/aho-corasick-0.6.4.tar.gz doesn't seem to exist in /usr/ports/distfiles/. +=> Attempting to fetch https://crates.io/api/v1/crates/aho-corasick/0.6.4/download?dummy=/rust/crates/aho-corasick-0.6.4.tar.gz +rust/crates/aho-corasick-0.6.4.tar.gz 100% of 24 kB 6139 kBps 00m00s +=> rust/crates/ansi_term-0.11.0.tar.gz doesn't seem to exist in /usr/ports/distfiles/. +=> Attempting to fetch https://crates.io/api/v1/crates/ansi_term/0.11.0/download?dummy=/rust/crates/ansi_term-0.11.0.tar.gz +rust/crates/ansi_term-0.11.0.tar.gz 100% of 16 kB 21 MBps 00m00s +=> rust/crates/arrayvec-0.4.7.tar.gz doesn't seem to exist in /usr/ports/distfiles/. +=> Attempting to fetch https://crates.io/api/v1/crates/arrayvec/0.4.7/download?dummy=/rust/crates/arrayvec-0.4.7.tar.gz +rust/crates/arrayvec-0.4.7.tar.gz 100% of 22 kB 3237 kBps 00m00s +=> rust/crates/atty-0.2.9.tar.gz doesn't seem to exist in /usr/ports/distfiles/. +=> Attempting to fetch https://crates.io/api/v1/crates/atty/0.2.9/download?dummy=/rust/crates/atty-0.2.9.tar.gz +rust/crates/atty-0.2.9.tar.gz 100% of 5898 B 81 MBps 00m00s +=> rust/crates/bitflags-1.0.1.tar.gz doesn't seem to exist in /usr/ports/distfiles/. +[...]</screen> + + <para>Atualmente, o diretório de trabalho contém apenas os fontes dos aplicativos que nós extraímos como parte do passo <command>make cargo-crates</command>. Antes de tentar compilar o port, o diretório de trabalho deve ser limpo, para que os fontes do crate possam ser extraídos para o <varname>CARGO_VENDOR_DIR</varname>: </para> + + <screen><prompt>%</prompt> <userinput>make clean</userinput> +===> Cleaning for tokei-7.0.2</screen> + + <para>O port está agora pronto para uma compilação de teste e ajustes adicionais, como criar um plist, escrever uma descrição, adicionar informações de licença, opções, etc. como é normal.</para> + </example> + + <example xml:id="cargo-ex2"> + <title>Ativando Recursos Adicionais do Aplicativo</title> + + <para>Alguns aplicativos definem recursos adicionais em seus <filename>Cargo.toml</filename>. Eles podem ser compilados definindo a variável <varname>CARGO_FEATURES</varname> no port.</para> + + <para>Aqui nós habilitamos as features Tokei's <literal>json</literal> e <literal>yaml</literal>:</para> + + <programlisting>CARGO_FEATURES= json yaml</programlisting> + </example> + + <example xml:id="cargo-ex3"> + <title>Listando Licenças Crate</title> + + <para>Os crates têm suas próprias licenças. É importante saber o que elas são ao adicionar o bloco <varname>LICENSE</varname> para o port (ver<xref linkend="licenses"/>). O target auxiliar <buildtarget>cargo-crates-licenses</buildtarget> tentará listar todas as licenças de todos os crates definidos no <varname>CARGO_CRATES</varname>.</para> + + <screen><prompt>%</prompt> <userinput>make cargo-crates-licenses</userinput> +aho-corasick-0.6.4 Unlicense/MIT +ansi_term-0.11.0 MIT +arrayvec-0.4.7 MIT/Apache-2.0 +atty-0.2.9 MIT +bitflags-1.0.1 MIT/Apache-2.0 +byteorder-1.2.2 Unlicense/MIT +[...]</screen> + + <note> + <para>Os nomes das licenças geradas com <command>make cargo-create-licenses</command> são expressões de licenças do SPDX 2.1 que não correspondem aos nomes de licença definidos na estrutura de ports. Eles precisam ser traduzidos para os nomes de <xref linkend="licenses-license-list"/>.</para> + </note> + </example> + </sect2> + </sect1> + + <sect1 xml:id="using-autotools"> + <title>Usando o GNU Autotools</title> + + <para>Se um port precisar de algum software GNU Autotools, adicione <literal>USES=autoreconf</literal>. Veja <xref linkend="uses-autoreconf"/> Para maiores informações.</para> + </sect1> + + <sect1 xml:id="using-gettext"> + <title>Usando o GNU <literal>gettext</literal></title> + + <sect2 xml:id="using-gettext-basic"> + <title>Uso Básico</title> + + <para>Se o port requer o <literal>gettext</literal>, defina <literal>USES=gettext</literal>, e o port herdará a dependência <filename>libintl.so</filename> do <package role="port">devel/gettext</package>. Outros valores para uso do <literal>gettext</literal> estão listados em <link linkend="uses-gettext"><literal>USES=gettext</literal></link>.</para> + + <para>Um caso bastante comum é um port que utilize o <literal>gettext</literal> e o <command>configure</command>. Geralmente, o GNU <command>configure</command> deve ser capaz de localizar o <literal>gettext</literal> automaticamente.</para> + + <programlisting>USES= gettext +GNU_CONFIGURE= yes</programlisting> + + <para>Se falhar, dicas da localização do <literal>gettext</literal> podem ser informados por meio do <envar>CPPFLAGS</envar> e <envar>LDFLAGS</envar> do seguinte modo:</para> + + <programlisting>USES= gettext +CPPFLAGS+= -I${LOCALBASE}/include +LDFLAGS+= -L${LOCALBASE}/lib + +GNU_CONFIGURE= yes</programlisting> + </sect2> + + <sect2 xml:id="using-gettext-optional"> + <title>Uso Opcional</title> + + <para>Alguns softwares permitem desabilitar o <acronym>NLS</acronym>. Por exemplo, passando <option>--disable-nls</option> para o <command>configure</command>. Nesse caso, o port deve usar <literal>gettext</literal> condicionalmente, dependendo do status da opção <literal>NLS</literal>. Para ports de baixa a média complexidade, use este idioma: </para> + + <programlisting>GNU_CONFIGURE= yes + +OPTIONS_DEFINE= NLS +OPTIONS_SUB= yes + +NLS_USES= gettext +NLS_CONFIGURE_ENABLE= nls + +.include <bsd.port.mk></programlisting> + + <para>Ou usando a maneira antiga de usar opções:</para> + + <programlisting>GNU_CONFIGURE= yes + +OPTIONS_DEFINE= NLS + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MNLS} +USES+= gettext +PLIST_SUB+= NLS="" +.else +CONFIGURE_ARGS+= --disable-nls +PLIST_SUB+= NLS="@comment " +.endif + +.include <bsd.port.mk></programlisting> + + <para>O próximo item na lista de tarefas a fazer é organizar de forma condicional os arquivos do catálogo de mensagens na lista de pacotes. A parte do <filename>Makefile</filename> desta tarefa já é fornecida pela expressão idiomática. Isto é explicado na seção sobre <link linkend="plist-sub">práticas avançadas de <filename>pkg-plist</filename></link>. Em poucas palavras, cada ocorrência de <literal>%%NLS%%</literal> dentro de <filename>pkg-plist</filename> será substituído por <quote><literal>@Comment</literal></quote> se o NLS estiver desativado ou por uma cadeia nula se o NLS estiver ativado. Consequentemente, as linhas prefixadas por <literal>%%NLS%%</literal> se tornarão meros comentários na lista de empacotamento final se o NLS estiver desativado; caso contrário, o prefixo será deixado de fora. Em seguida, insira <literal>%%NLS%%</literal> antes de cada caminho para um arquivo de catálogo de mensagens em <filename>pkg-plist</filename>. Por exemplo:</para> + + <programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo +%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting> + + <para>Em casos de alta complexidade, técnicas mais avançadas podem ser necessárias, como <link linkend="plist-dynamic"> geração dinâmica de lista de empacotamento</link></para> + </sect2> + + <sect2 xml:id="using-gettext-catalog-directories"> + <title>Manipulando Diretórios do Catálogo de Mensagens</title> + + <para>Há um ponto a ser observado sobre a instalação de arquivos de catálogo de mensagens. Os diretórios de destino para eles, que residem em <filename>LOCALBASE/share/locale</filename>, não devem ser criados e removidos por um port. Os idiomas mais populares têm seus respectivos diretórios listados em <filename>PORTSDIR/Templates/BSD.local.dist</filename>. Os diretórios para muitos outros idiomas são governados pelo port <package role="port">devel/gettext</package>. Consulte o seu <filename>pkg-plist</filename> e veja se o port vai instalar um arquivo de catálogo de mensagens para um idioma exclusivo. </para> + </sect2> + </sect1> + + <sect1 xml:id="using-perl"> + <title>Usando <application>Perl</application></title> + + <para>E se o <varname>MASTER_SITES</varname> estiver configurado para <literal>CPAN</literal>, o subdiretório correto é geralmente selecionado automaticamente. Se o subdiretório padrão estiver errado, o <literal>CPAN/Module</literal> pode ser usado para alterá-lo. O <varname>MASTER_SITES</varname> também pode ser definido para o antigo <varname>MASTER_SITE_PERL_CPAN</varname>, então o valor preferido para o <varname>MASTER_SITE_SUBDIR</varname> é o nome da hierarquia de nível superior. Por exemplo, o valor recomendado para <literal>p5-Module-Name</literal> é <literal>Module</literal>. A hierarquia de nível superior pode ser examinada em <link xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>. Isso mantém o port funcionando quando o autor do módulo muda. </para> + + <para>A exceção a essa regra é quando o diretório relevante não existe ou o distfile não existe neste diretório. Neste caso, é permitido usar o id do autor como <varname>MASTER_SITE_SUBDIR</varname>. A macro <literal>CPAN: AUTOR</literal> pode ser usada, a qual será traduzida para o diretório de autor com hash. Por exemplo,<literal>CPAN: AUTOR</literal> será convertido para <literal>autores/id/A/AU/AUTOR</literal>.</para> + + <para>Quando um port precisa de suporte a <application>Perl</application>, ele deve definir <literal>USES=perl5</literal> com o opcional <varname>USE_PERL5</varname> descrito em <link linkend="uses-perl5">descrição do USES no perl5</link>.</para> + + <table frame="none" xml:id="using-perl-variables"> + <title>Variáveis Somente Leitura para Ports Que Usam <application>Perl</application></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variáveis Somente de Leitura</entry> + <entry>Significa</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>PERL</varname></entry> + <entry>O caminho completo do interpretador Perl 5, seja no sistema ou instalado a partir de um port, mas sem o número da versão. Use isso quando o software precisar do caminho para o interpretador <application>Perl</application>. Para substituir as linhas <quote><literal>#!</literal></quote> em scripts, use <link linkend="uses-shebangfix">USES=shebangfix</link>.</entry> + </row> + + <row> + <entry><varname>PERL_VERSION</varname></entry> + <entry>A versão completa do Perl instalada (por exemplo, <literal>5,8,9</literal>).</entry> + </row> + + <row> + <entry><varname>PERL_LEVEL</varname></entry> + <entry>A versão do Perl instalada como um inteiro no formato <literal>MNNNPP</literal> (por exemplo,<literal>500809</literal>).</entry> + </row> + + <row> + <entry><varname>PERL_ARCH</varname></entry> + <entry>Local no qual o Perl armazena as bibliotecas dependentes da arquitetura. O valor padrão aponta para <literal>${ARCH}-freebsd</literal>.</entry> + </row> + + <row> + <entry><varname>PERL_PORT</varname></entry> + <entry>Nome do port Perl instalado (por exemplo,<literal>perl5</literal>).</entry> + </row> + + <row> + <entry><varname>SITE_PERL</varname></entry> + <entry>Nome do diretório para onde vão os pacotes Perl específicos do site. Esse valor é adicionado a <varname>PLIST_SUB</varname>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <note> + <para>Ports de Módulos Perl que não possuem um site oficial devem linkar para <systemitem>cpan.org</systemitem> na linha WWW do <filename>pkg-descr</filename>. O formato preferido para a URL é <literal>http://search.cpan.org/dist/Module-Name/</literal> (incluindo a barra final).</para> + </note> + + <note> + <para>Não use <literal>${SITE_PERL}</literal> em declarações de dependência. Fazê-lo pressupõe que o <filename>perl5.mk</filename> foi incluído, o que nem sempre é verdade. Os ports que dependem desse port terão dependências incorretas se os arquivos desse port forem movidos posteriormente em uma atualização. O caminho certo para declarar as dependências do módulo Perl é mostrado no exemplo abaixo. </para> + </note> + + <example xml:id="use-perl-dependency-example"> + <title>Exemplo de Dependência Perl</title> + + <programlisting>p5-IO-Tee>=0.64:devel/p5-IO-Tee</programlisting> + </example> + + <para>Para ports Perl que instalam páginas de manual, as macros <literal>PERL5_MAN3</literal> e <literal>PERL5_MAN1</literal> podem ser usadas dentro do <filename>pkg-plist</filename>. Por exemplo,</para> + + <programlisting>lib/perl5/5.14/man/man1/event.1.gz +lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz</programlisting> + + <para>pode ser substituído por</para> + + <programlisting>%%PERL5_MAN1%%/event.1.gz +%%PERL5_MAN3%%/AnyEvent::I3.3.gz</programlisting> + + <note> + <para>Não existem macros <varname>PERL5_MAN<replaceable>x</replaceable></varname> para as outras seções (sendo <replaceable>x</replaceable> igual a <literal>2</literal> e de <literal>4</literal> até <literal>9</literal>) porque estes são instalados nos diretórios comuns. </para> + </note> + + <example xml:id="use-perl-ex-build"> + <title>Um Port Que Requer Perl Apenas para Compilar</title> + + <para>Como o valor padrão para USE_PERL5 é build e run, configure-o para:</para> + + <programlisting>USES= perl5 +USE_PERL5= build</programlisting> + </example> + + <example xml:id="use-perl-ex-patch"> + <title>Um Port Que Também Requer Perl Para Patch</title> + + <para>De tempos em tempos, o uso do <citerefentry><refentrytitle>sed</refentrytitle><manvolnum>1</manvolnum></citerefentry> para patches se torna insuficiente. Quando usar <citerefentry><refentrytitle>perl</refentrytitle><manvolnum>1</manvolnum></citerefentry> fica mais facil, para isso utilize:</para> + + <programlisting>USES= perl5 +USE_PERL5= patch build run</programlisting> + </example> + + <example xml:id="use-perl-ex-configure"> + <title>Um Módulo Perl Que Precisa de <literal>ExtUtils::MakeMaker</literal> para Compilar</title> + + <para>A maioria dos módulos <application>Perl</application> vêm com um script configure <filename>Makefile.PL</filename>. Neste caso, defina:</para> + + <programlisting>USES= perl5 +USE_PERL5= configure</programlisting> + </example> + + <example xml:id="use-perl-ex-modbuild"> + <title>Um Módulo Perl Que Precisa <literal>Módulo::Build</literal> para Compilar</title> + + <para>Quando um modulo <application>Perl</application> vem com um script configure <filename>Build.PL</filename>, pode exigir <application>Module:Build</application>, nesse caso, defina</para> + + <programlisting>USES= perl5 +USE_PERL5= modbuild</programlisting> + + <para>Se for ao contrário, e exigir <application>Module::Build::Tiny</application>, defina </para> + + <programlisting>USES= perl5 +USE_PERL5= modbuildtiny</programlisting> + </example> + </sect1> + + <sect1 xml:id="using-x11"> + <title>Usando o X11</title> + + <sect2 xml:id="x11-variables"> + <title>Componentes X.Org</title> + + <para>A implementação do X11 disponível na Coleção de Ports é o X.Org. Se o aplicativo depender de componentes X, defina <varname>USE_XORG</varname> a lista de componentes necessários. Componentes disponíveis, no momento da escrita, são: </para> + + <para><literal>bigreqsproto compositeproto damageproto dmx dmxproto dri2proto dri3proto evieproto fixesproto fontcacheproto fontenc fontsproto fontutil glproto ice inputproto kbproto libfs oldx pciaccess pixman presentproto printproto randrproto recordproto renderproto resourceproto scrnsaverproto sm trapproto videoproto x11 xau xaw xaw6 xaw7 xbitmaps xcb xcmiscproto xcomposite xcursor xdamage xdmcp xevie xext xextproto xf86bigfontproto xf86dgaproto xf86driproto xf86miscproto xf86rushproto xf86vidmodeproto xfixes xfont xfontcache xft xi xinerama xineramaproto xkbfile xkbui xmu xmuu xorg-macros xorg-server xp xpm xprintapputil xprintutil xproto xproxymngproto xrandr xrender xres xscrnsaver xshmfence xt xtrans xtrap xtst xv xvmc xxf86dga xxf86misc xxf86vm</literal>.</para> + + <para>A lista sempre atualizada pode ser encontrada em <filename>/usr/ports/Mk/bsd.xorg.mk</filename></para> + + <para>O Projeto Mesa é um esforço para fornecer implementação gratuita do OpenGL. Para especificar uma dependência em vários componentes deste projeto, use a variável <varname>USE_GL</varname>. Opções válidas são: <literal>egl, gl, glesv2, glew, glu, glut, glw</literal> e <literal>linux</literal>. Para compatibilidade com versões anteriores, o valor de <literal>yes</literal> direciona para <literal>glu</literal>.</para> + + <example xml:id="use-xorg-example"> + <title>Exemplo <varname>USE_XORG</varname></title> + + <programlisting>USE_XORG= xrender xft xkbfile xt xaw +USE_GL= glu</programlisting> + </example> + + <table frame="none" xml:id="using-xorg-variables"> + <title>Variáveis para Ports Que Usam X</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><varname>USES= imake</varname></entry> + <entry>O port usa <command>imake</command></entry> + </row> + + <row> + <entry><varname>XMKMF</varname></entry> + <entry>Definir o caminho de <command>xmkmf</command> se não no <envar>PATH</envar>. Padrão para <literal>xmkmf -a</literal>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="using-x11-vars"> + <title>Usando Variáveis Relacionadas ao X11</title> + + <programlisting># Use some X11 libraries +USE_XORG= x11 xpm</programlisting> + </example> + </sect2> + + <sect2 xml:id="x11-motif"> + <title>Ports que Requerem Motif</title> + + <para>Se o port requer uma biblioteca Motif, defina <varname>USES=motif</varname> no <filename>Makefile</filename>. A implementação padrão do Motif é <package role="port">x11-toolkits/open-motif</package>. Os usuários podem escolher o <package role="port">x11-toolkits/lesstif</package> em vez disso, definindo <varname>WANT_LESSTIF</varname> no seu <filename>make.conf</filename>.</para> + + <para>O <varname>MOTIFLIB</varname> será definido por <filename>motif.mk</filename> para referenciar a biblioteca Motif apropriada. Por favor, corrija o fonte do port para usar <literal>${MOTIFLIB}</literal> onde quer que a biblioteca Motif seja referenciada no <filename>Makefile</filename> original ou no <filename>Imakefile</filename>.</para> + + <para>Existem dois casos comuns:</para> + + <itemizedlist> + <listitem> + <para>Se o port se referir à biblioteca Motif como <literal>-lXm</literal> em seu <filename>Makefile</filename> ou <filename>Imakefile</filename>, substitua <literal>${MOTIFLIB}</literal> por isso.</para> + </listitem> + + <listitem> + <para>Se o port usa <literal>XmClientLibs</literal> em seu <filename>Imakefile</filename>, mude para <literal>${MOTIFLIB} ${XTOOLLIB} ${XLIB}</literal>.</para> + </listitem> + </itemizedlist> + + <para>Observe que o <varname>MOTIFLIB</varname> (geralmente) se expande para <literal>-L/usr/local/lib -lXm -lXp</literal> ou <literal>/usr/local/lib/libXm.a</literal>, então não há necessidade de adicionar <literal>-L</literal> ou <literal>-l</literal> na frente.</para> + </sect2> + + <sect2 xml:id="x11-fonts"> + <title>Fontes X11</title> + + <para>Se o port instalar fontes para o X Window System, coloque-as em <filename>LOCALBASE/lib/X11/fontes/local</filename>.</para> + </sect2> + + <sect2 xml:id="x11-fake-display"> + <title>Obtendo um <envar>DISPLAY</envar> Falso com Xvfb</title> + + <para>Algumas aplicações requerem uma tela X11 funcional para que a compilação seja bem-sucedida. Isso representa um problema para as máquinas que operam sem um monitor. Quando essa variável é usada, a infraestrutura de compilação iniciará o X virtual framebuffer. Um <envar>DISPLAY</envar> funcional é então passado para a compilação. Veja <link linkend="uses-display"><literal>USES=exibição</literal></link> para os possíveis argumentos.</para> + + <programlisting>USES= display</programlisting> + </sect2> + + <sect2 xml:id="desktop-entries"> + <title>Entradas de Desktop</title> + + <para>Entradas de desktop (<link xlink:href="http://standards.freedesktop.org/desktop-entry-spec/latest/">um padrão Freedesktop</link>) fornecem uma maneira de ajustar automaticamente os recursos do desktop quando um novo programa é instalado, sem a necessidade de intervenção do usuário. Por exemplo, programas recém-instalados aparecem automaticamente nos menus de aplicativos de ambientes de desktop compatíveis. Entradas de Desktop surgiram no ambiente de desktop <application>GNOME</application>, mas agora são um padrão e também funcionam com o <application>KDE</application> e o <application>Xfce</application>. Esta pitada de automação fornece um benefício real para o usuário, e as entradas de desktop são incentivadas para aplicativos que podem ser usados em um ambiente desktop. </para> + + <sect3 xml:id="desktop-entries-predefined"> + <title>Usando Arquivos <filename>.desktop</filename> Pré-definidos</title> + + <para>Ports que incluem <filename><replaceable>*</replaceable>.desktop</filename> pré-definidos devem incluir estes arquivos no <filename>pkg-plist</filename> e instalá-los no diretório <filename>$LOCALBASE/share/applications</filename>. A macro <link linkend="install-macros"><varname>INSTALL_DATA</varname></link> é útil para instalar esses arquivos. </para> + </sect3> + + <sect3 xml:id="updating-desktop-database"> + <title>Atualizando o Banco de Dados do Desktop</title> + + <para>Se um port tiver uma entrada MimeType em seu <filename><replaceable>portname</replaceable>.desktop</filename>, o banco de dados do desktop deve ser atualizado após a instalação e desinstalação. Para fazer isso, defina <varname>USES</varname>= desktop-file-utils. </para> + </sect3> + + <sect3 xml:id="desktop-entries-macro"> + <title>Criando Entradas de Desktop com <varname>DESKTOP_ENTRIES</varname></title> + + <para>As entradas desktop podem ser facilmente criadas para aplicativos usando <varname>DESKTOP_ENTRIES</varname>. Um arquivo chamado <filename><replaceable>name</replaceable>.desktop</filename> será criado, instalado e adicionado ao <filename>pkg-plist</filename> automaticamente. A sintaxe é: </para> + + <programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting> + + <para>A lista de possíveis categorias está disponível no <link xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">Site Freedesktop</link>. <varname>StartupNotify</varname> indica se a aplicação é compatível com <emphasis>notificações de inicialização</emphasis>. Estes são tipicamente um indicador gráfico como um relógio que aparece no ponteiro do mouse, menu ou painel para dar ao usuário uma indicação quando um programa está sendo iniciado. Um programa que seja compatível com as notificações de inicialização limpa o indicador depois de iniciado. Programas que não são compatíveis com as notificações de inicialização nunca limpariam o indicador (possivelmente confundindo e enfurecendo o usuário) e devem ter <varname>StartupNotify</varname> definido como <literal>false</literal> então o indicador não é mostrado. </para> + + <para>Exemplo:</para> + + <programlisting>DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ + "${DATADIR}/xtra/graf/tome-128.png" \ + "tome -v -g" "Application;Game;RolePlaying;" \ + false</programlisting> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="using-gnome"> + <title>Usando o GNOME</title> + + <sect2 xml:id="using-gnome-introduction"> + <title>Introdução</title> + + <para>Este capítulo explica a estrutura do framework <acronym>GNOME</acronym> utilizado pelos ports. O framework pode ser dividido livremente nos componentes base, componentes desktop <acronym>GNOME</acronym> e algumas macros especiais que simplificam o trabalho dos mantenedores dos ports.</para> + + <para>Ao desenvolver um port ou modificar um, por favor, defina</para> + + <programlisting>DEVELOPER=yes</programlisting> + + <para>no ambiente ou em <filename>/etc/make.conf</filename>. Isso faz com que o framework do ports ative verificações adicionais.</para> + </sect2> + + <sect2 xml:id="use-gnome"> + <title>Usando <varname>USE_GNOME</varname></title> + + <para>Adicionar esta variável ao port permite o uso das macros e componentes definidos em <filename>bsd.gnome.mk</filename>. O código em <filename>bsd.gnome.mk</filename> adiciona as dependências de tempo de compilação, tempo de execução ou biblioteca necessárias ou o tratamento de arquivos especiais. Aplicativos <acronym>GNOME</acronym> sob o FreeBSD usam o framework <varname>USE_GNOME</varname>. Inclua todos os componentes necessários como uma lista separada por espaço. Os componentes <varname>USE_GNOME</varname> são divididos nessas listas virtuais: componentes básicos, componentes do GNOME 3 e componentes legados. Se o port precisa apenas de bibliotecas GTK3, este é o caminho mais curto para defini-lo: </para> + + <programlisting>USE_GNOME= gtk30</programlisting> + + <para>Componentes <varname>USE_GNOME</varname> adicionam automaticamente as dependências de que precisam. Por favor, veja <xref linkend="gnome-components"/>para uma lista exaustiva de todos componentes <varname>USE_GNOME</varname> e quais outros componentes eles implicam e suas dependências.</para> + + <para>Aqui está um exemplo de <filename>Makefile</filename> para um port do GNOME que usa muitas das técnicas descritas neste documento. Por favor, use-o como um guia para criar novos ports. </para> + + <programlisting># $FreeBSD$ + +PORTNAME= regexxer +DISTVERSION= 0.10 +CATEGORIES= devel textproc gnome +MASTER_SITES= GNOME + +MAINTAINER= kwm@FreeBSD.org +COMMENT= Interactive tool for performing search and replace operations + +USES= gettext gmake pathfix pkgconfig tar:xz +GNU_CONFIGURE= yes +USE_GNOME= gnomeprefix intlhack gtksourceviewmm3 +CPPFLAGS+= -I${LOCALBASE}/include +LDFLAGS+= -L${LOCALBASE}/lib +INSTALLS_ICONS= yes + +GLIB_SCHEMAS= org.regexxer.gschema.xml + +.include <bsd.port.mk></programlisting> + + <note> + <para>A macro <varname>USE_GNOME</varname> se utilizada sem nenhum argumento não irá adicionar nenhuma dependência ao port. O <varname>USE_GNOME</varname> não pode ser definido depois do <filename>bsd.port.pre.mk</filename>.</para> + </note> + </sect2> + + <sect2 xml:id="using-gnome-variables"> + <title>Variáveis</title> + + <para>Esta seção explica quais macros estão disponíveis e como elas são usadas. Como elas são usadas no exemplo acima. A <xref linkend="gnome-components"/> tem uma explicação mais detalhada. A variável <varname>USE_GNOME</varname> precisa ser definido para que essas macros sejam úteis. </para> + + <variablelist> + <varlistentry> + <term xml:id="gnome-icons"><varname>INSTALLS_ICONS</varname></term> + + <listitem> + <para>Ports <application>GTK+</application> que instalam ícones de estilo <application>Freedesktop</application> em <filename>${LOCALBASE}/share/icons</filename> deve usar essa macro para garantir que os ícones sejam armazenados em cache e exibidos corretamente. O arquivo de cache é nomeado <filename>icon-theme.cache</filename>. Não inclua esse arquivo em <filename>pkg-plist</filename>. Essa macro manipula isso automaticamente. Esta macro não é necessária para <application>Qt</application>, que usam um método interno.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:id="gnome-glibschema"><varname>GLIB_SCHEMAS</varname></term> + + <listitem> + <para>Lista de todos os arquivos de esquema de glib que o port instala. A macro adicionará os arquivos ao plist do port e manipulará o registro destes arquivos na instalação e desinstalação.</para> + + <para>Os arquivos de esquema do glib são escritos em <acronym>XML</acronym> e terminam com a extensão <filename>gschema.xml</filename>. Eles estão instalados no diretório <filename>share/glib-2.0/schemas/</filename>. Esses arquivos de esquema contêm todos os valores de configuração do aplicativo com as configurações padrão. O banco de dados real usado pelos aplicativos é construído por <application>glib-compile-schema</application>, que é executado pela macro <varname>GLIB_SCHEMAS</varname>. </para> + + <programlisting>GLIB_SCHEMAS=foo.gschema.xml</programlisting> + + <note> + <para>Não adicione esquemas simplificados ao <filename>pkg-plist</filename>. Se eles estão listados em <filename>pkg-plist</filename>, eles não serão registrados e os aplicativos podem não funcionar corretamente.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:id="gnome-gconfschema"><varname>GCONF_SCHEMAS</varname></term> + + <listitem> + <para>Liste todos os arquivos do esquema gconf. A macro adicionará os arquivos de esquema ao plist do port e manipulará seu registro na instalação e desinstalação. </para> + + <para>O GConf é o banco de dados baseado em <acronym>XML</acronym> que praticamente todos os aplicativos GNOME usam para armazenar suas configurações. Esses arquivos são instalados no banco de dados no diretório <filename>etc/gconf/schemas</filename>. Esse banco de dados é definido pelos arquivos de esquema instalados que são usados para gerar os arquivos chave <filename>%gconf.xml</filename>. Para cada arquivo de esquema instalado pelo port, existe uma entrada no <filename>Makefile</filename>: </para> + + <programlisting>GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas</programlisting> + + <note> + <para>Os esquemas do Gconf estão listados na macro <varname>GCONF_SCHEMAS</varname> em vez do <filename>pkg-plist</filename>. Se eles estiverem listados em <filename>pkg-plist</filename>, eles não serão registrados e os aplicativos podem não funcionar corretamente.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term xml:id="gnome-omf"><varname>INSTALLS_OMF</varname></term> + + <listitem> + <para>Os arquivos do Open Source Metadata Framework (<acronym>OMF</acronym>) são comumente usados pelos aplicativos GNOME 2. Esses arquivos contêm as informações do arquivo de ajuda do aplicativo e requerem processamento especial pelo ScrollKeeper/rarian. Para registrar adequadamente arquivos <acronym>OMF</acronym> ao instalar aplicativos GNOME a partir de pacotes, certifique-se de que os arquivos <varname>omf</varname> estão listados em <varname>pkg-plist</varname> e que o <filename>Makefile</filename> do port tem o <varname>INSTALLS_OMF</varname> definido:</para> + + <programlisting>INSTALLS_OMF=yes</programlisting> + + <para>Quando definido, <filename>bsd.gnome.mk</filename> digitaliza automaticamente o <filename>pkg-plist</filename> e adiciona diretivas <literal>@exec</literal> e <literal>@unexec</literal> para cada <filename>.omf</filename>para rastrear no banco de dados de registro do <acronym>OMF</acronym>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> + + <sect1 xml:id="gnome-components"> + <title>Componentes GNOME</title> + + <para>Para mais ajuda com um port GNOME, veja alguns dos <link xlink:href="@@URL_RELPREFIX@@/ports/gnome.html">ports existentes</link> por exemplo. A pagina <link xlink:href="@@URL_RELPREFIX@@/gnome/"> GNOME do FreeBSD</link> tem informações de contato, se precisar de mais ajuda. Os componentes são divididos em componentes GNOME que estão atualmente em uso e componentes legados. Se o componente suportar argumento, eles serão listados entre parênteses na descrição. O primeiro é o padrão. "Ambos" são mostrados se o componente usar como padrão a adição às dependências de construção e execução. </para> + + <table xml:id="gnome-components-list"> + <title>Componentes GNOME</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Componente</entry> + <entry>Programa associado</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>atk</literal></entry> + <entry>accessibility/atk</entry> + <entry>Kit de ferramentas de acessibilidade (ATK)</entry> + </row> + + <row> + <entry><literal>atkmm</literal></entry> + <entry>accessibility/atkmm</entry> + <entry>c++ bindings para atk</entry> + </row> + + <row> + <entry><literal>cairo</literal></entry> + <entry>graphics/cairo</entry> + <entry>Biblioteca de gráficos vetoriais com suporte a saída entre dispositivos</entry> + </row> + + <row> + <entry><literal>cairomm</literal></entry> + <entry>graphics/cairomm</entry> + <entry>c++ bindings para o cairo</entry> + </row> + + <row> + <entry><literal>dconf</literal></entry> + <entry>devel/dconf</entry> + <entry>Sistema de banco de dados de configuração (both, buil, run)</entry> + </row> + + <row> + <entry><literal>evolutiondataserver3</literal></entry> + <entry>databases/evolution-data-server</entry> + <entry>Backends de dados para a suíte mail/PIM integrada do Evolution</entry> + </row> + + <row> + <entry><literal>gdkpixbuf2</literal></entry> + <entry>graphics/gdk-pixbuf2</entry> + <entry>Biblioteca de gráficos para GTK+</entry> + </row> + + <row> + <entry><literal>glib20</literal></entry> + <entry>devel/glib20</entry> + <entry>Biblioteca core do GNOME<literal>glib20</literal></entry> + </row> + + <row> + <entry><literal>glibmm</literal></entry> + <entry>devel/glibmm</entry> + <entry>c++ bindings para glib20</entry> + </row> + + <row> + <entry><literal>gnomecontrolcenter3</literal></entry> + <entry>sysutils/gnome-control-center</entry> + <entry>Centro de Controle do GNOME 3</entry> + </row> + + <row> + <entry><literal>gnomedesktop3</literal></entry> + <entry>x11/gnome-desktop</entry> + <entry>Biblioteca de interface do usuário do desktop GNOME 3</entry> + </row> + + <row> + <entry><literal>gsound</literal></entry> + <entry>audio/gsound</entry> + <entry>Biblioteca GObject para reproduzir sons do sistema (both, build, run)</entry> + </row> + + <row> + <entry><literal>gtk-update-icon-cache</literal></entry> + <entry>graphics/gtk-update-icon-cache</entry> + <entry>Utilitário Gtk-update-icon-cache do kit de ferramentas Gtk +</entry> + </row> + + <row> + <entry><literal>gtk20</literal></entry> + <entry>x11-toolkits/gtk20</entry> + <entry>Kit de ferramentas Gtk+ 2</entry> + </row> + + <row> + <entry><literal>gtk30</literal></entry> + <entry>x11-toolkits/gtk30</entry> + <entry>Kit de ferramentas Gtk+ 3</entry> + </row> + + <row> + <entry><literal>gtkmm20</literal></entry> + <entry>x11-toolkits/gtkmm20</entry> + <entry>c++ bindings 2.0 para o kit de ferramentas gtk20</entry> + </row> + + <row> + <entry><literal>gtkmm24</literal></entry> + <entry>x11-toolkits/gtkmm24</entry> + <entry>c++ bindings 2.4 para o kit de ferramentas gtk20</entry> + </row> + + <row> + <entry><literal>gtkmm30</literal></entry> + <entry>x11-toolkits/gtkmm30</entry> + <entry>c++ bindings 3.0 para o kit de ferramentas gtk30</entry> + </row> + + <row> + <entry><literal>gtksourceview2</literal></entry> + <entry>x11-toolkits/gtksourceview2</entry> + <entry>Widget que adiciona destaque de sintaxe para o GtkTextView</entry> + </row> + + <row> + <entry><literal>gtksourceview3</literal></entry> + <entry>x11-toolkits/gtksourceview3</entry> + <entry>Widget de texto que adiciona destaque de sintaxe ao widget GtkTextView</entry> + </row> + + <row> + <entry><literal>gtksourceviewmm3</literal></entry> + <entry>x11-toolkits/gtksourceviewmm3</entry> + <entry>c++ bindings para a biblioteca gtksourceview3</entry> + </row> + + <row> + <entry><literal>gvfs</literal></entry> + <entry>devel/gvfs</entry> + <entry>Sistema de arquivos virtual do GNOME</entry> + </row> + + <row> + <entry><literal>intltool</literal></entry> + <entry>textproc/intltool</entry> + <entry>Ferramenta para Internacionalização (veja também intlhack)</entry> + </row> + + <row> + <entry><literal>introspection</literal></entry> + <entry>devel/gobject-introspection</entry> + <entry>Ligações de introspecção e ferramentas básicas para gerar ligações de introspecção. Na maioria das vezes: build é suficiente, e :both/:run só é necessário para aplicativos que usam ligações de introspecção. (both, build, run)</entry> + </row> + + <row> + <entry><literal>libgda5</literal></entry> + <entry>databases/libgda5</entry> + <entry>Fornece acesso uniforme a diferentes tipos de fontes de dados</entry> + </row> + + <row> + <entry><literal>libgda5-ui</literal></entry> + <entry>databases/libgda5-ui</entry> + <entry>Biblioteca de interface do usuário da biblioteca libgda5</entry> + </row> + + <row> + <entry><literal>libgdamm5</literal></entry> + <entry>databases/libgdamm5</entry> + <entry>c++ bindings para a biblioteca libgda5</entry> + </row> + + <row> + <entry><literal>libgsf</literal></entry> + <entry>devel/libgsf</entry> + <entry>Abstração extensível de I/O para lidar com formatos de arquivo estruturados</entry> + </row> + + <row> + <entry><literal>librsvg2</literal></entry> + <entry>graphics/librsvg2</entry> + <entry>Biblioteca para analisar e renderizar arquivos gráficos vetoriais SVG</entry> + </row> + + <row> + <entry><literal>libsigc++20</literal></entry> + <entry>devel/libsigc++20</entry> + <entry>Framework de Callback para C++</entry> + </row> + + <row> + <entry><literal>libxml++26</literal></entry> + <entry>textproc/libxml++26</entry> + <entry>c++ bindings para a biblioteca libxml2</entry> + </row> + + <row> + <entry><literal>libxml2</literal></entry> + <entry>textproc/libxml2</entry> + <entry>Biblioteca do parser XML (both, build, run)</entry> + </row> + + <row> + <entry><literal>libxslt</literal></entry> + <entry>textproc/libxslt</entry> + <entry>Biblioteca XSLT C (both, build, run)</entry> + </row> + + <row> + <entry><literal>metacity</literal></entry> + <entry>x11-wm/metacity</entry> + <entry>Gerenciador de janelas do GNOME</entry> + </row> + + <row> + <entry><literal>nautilus3</literal></entry> + <entry>x11-fm/nautilus</entry> + <entry>Gerenciador de arquivos GNOME</entry> + </row> + + <row> + <entry><literal>pango</literal></entry> + <entry>x11-toolkits/cave</entry> + <entry>Estrutura de código aberto para o layout e renderização do texto i18n</entry> + </row> + + <row> + <entry><literal>pangomm</literal></entry> + <entry>x11-toolkits/pangomm</entry> + <entry>c++ bindings para a biblioteca pango</entry> + </row> + + <row> + <entry><literal>py3gobject3</literal></entry> + <entry>devel/py3-gobject3</entry> + <entry>Python 3, GObject 3.0 bindings</entry> + </row> + + <row> + <entry><literal>pygobject3</literal></entry> + <entry>devel/py-gobject3</entry> + <entry>Python 2, GObject 3.0 bindings</entry> + </row> + + <row> + <entry><literal>vte3</literal></entry> + <entry>x11-toolkits/vte3</entry> + <entry>Widget de terminal com melhor acessibilidade e suporte I18N</entry> + </row> + </tbody> + </tgroup> + </table> + + <table xml:id="gnome-components-macro"> + <title>Componentes Macro do GNOME</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Componente</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>gnomeprefix</literal></entry> + <entry>Forneça <buildtarget>configure</buildtarget> com alguns locais padrão.</entry> + </row> + + <row> + <entry><literal>intlhack</literal></entry> + <entry>O mesmo que intltool, porém com os patches necessários para garantir o <filename>share/locale/</filename>. Por favor, use somente quando <literal>intltool</literal> sozinho não for suficiente.</entry> + </row> + + <row> + <entry><literal>referencehack</literal></entry> + <entry>Esta macro existe para ajudar a dividir a API ou a documentação de referência em seu próprio port.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table xml:id="gnome-components-legacy"> + <title>Componentes Legados do GNOME</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Componente</entry> + <entry>Programa associado</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>atspi</literal></entry> + <entry>accessibility/at-spi</entry> + <entry>Interface do Provedor de Serviços de Tecnologia Assistiva</entry> + </row> + + <row> + <entry><literal>esound</literal></entry> + <entry>audio/esound</entry> + <entry>Pacote de som do Enlightenment</entry> + </row> + + <row> + <entry><literal>gal2</literal></entry> + <entry>x11-toolkits/gal2</entry> + <entry>Coleção de widgets obtidos do GNOME 2 gnumeric</entry> + </row> + + <row> + <entry><literal>gconf2</literal></entry> + <entry>devel/gconf2</entry> + <entry>Sistema de banco de dados de configuração para o GNOME 2</entry> + </row> + + <row> + <entry><literal>gconfmm26</literal></entry> + <entry>devel/gconfmm26</entry> + <entry>c++ bindings para o gconf2</entry> + </row> + + <row> + <entry><literal>gdkpixbuf</literal></entry> + <entry>graphics/gdk-pixbuf</entry> + <entry>Biblioteca de gráficos para GTK+</entry> + </row> + + <row> + <entry><literal>glib12</literal></entry> + <entry>devel/glib12</entry> + <entry>biblioteca principal glib 1.2</entry> + </row> + + <row> + <entry><literal>gnomedocutils</literal></entry> + <entry>textproc/gnome-doc-utils</entry> + <entry>Utilitários de documentação para o GNOME</entry> + </row> + + <row> + <entry><literal>gnomemimedata</literal></entry> + <entry>misc/gnome-mime-data</entry> + <entry>MIME e banco de dados de aplicativos para o GNOME 2</entry> + </row> + + <row> + <entry><literal>gnomesharp20</literal></entry> + <entry>x11-toolkits/gnome-sharp20</entry> + <entry>Interfaces do GNOME 2 para o tempo de execução do .NET</entry> + </row> + + <row> + <entry><literal>gnomespeech</literal></entry> + <entry>accessibility/gnome-speech</entry> + <entry>API de conversão de texto em voz do GNOME 2</entry> + </row> + + <row> + <entry><literal>gnomevfs2</literal></entry> + <entry>devel/gnome-vfs</entry> + <entry>Sistema de Arquivos Virtual do GNOME 2</entry> + </row> + + <row> + <entry><literal>gtk12</literal></entry> + <entry>x11-toolkits/gtk12</entry> + <entry>Kit de ferramentas Gtk+ 1.2</entry> + </row> + + <row> + <entry><literal>gtkhtml3</literal></entry> + <entry>www/gtkhtml3</entry> + <entry>Mecanismo leve de renderização/impressão/edição de HTML</entry> + </row> + + <row> + <entry><literal>gtkhtml4</literal></entry> + <entry>www/gtkhtml4</entry> + <entry>Mecanismo leve de renderização/impressão/edição de HTML</entry> + </row> + + <row> + <entry><literal>gtksharp20</literal></entry> + <entry>x11-toolkits/gtk-sharp20</entry> + <entry>Interfaces GTK+ e GNOME 2 para o runtime .NET</entry> + </row> + + <row> + <entry><literal>gtksourceview</literal></entry> + <entry>x11-toolkits/gtksourceview</entry> + <entry>Widget que adiciona destaque de sintaxe para o GtkTextView</entry> + </row> + + <row> + <entry><literal>libartgpl2</literal></entry> + <entry>graphics/libart_lgpl</entry> + <entry>Biblioteca para gráficos 2D de alto desempenho</entry> + </row> + + <row> + <entry><literal>libbonobo</literal></entry> + <entry>devel/libbonobo</entry> + <entry>Componente e sistema de documentos compostos para o GNOME 2</entry> + </row> + + <row> + <entry><literal>libbonoboui</literal></entry> + <entry>x11-toolkits/libbonoboui</entry> + <entry>GUI frontend para o componente libbonobo do GNOME 2</entry> + </row> + + <row> + <entry><literal>libgda4</literal></entry> + <entry>databases/libgda4</entry> + <entry>Fornece acesso uniforme a diferentes tipos de fontes de dados</entry> + </row> + + <row> + <entry><literal>libglade2</literal></entry> + <entry>devel/libglade2</entry> + <entry>Biblioteca glade do GNOME 2</entry> + </row> + + <row> + <entry><literal>libgnome</literal></entry> + <entry>x11/libgnome</entry> + <entry>Bibliotecas para o GNOME 2, um ambiente de desktop GNU</entry> + </row> + + <row> + <entry><literal>libgnomecanvas</literal></entry> + <entry>graphics/libgnomecanvas</entry> + <entry>Biblioteca Gráfica para o GNOME 2</entry> + </row> + + <row> + <entry><literal>libgnomekbd</literal></entry> + <entry>x11/libgnomekbd</entry> + <entry>Biblioteca compartilhada de teclado do GNOME 2</entry> + </row> + + <row> + <entry><literal>libgnomeprint</literal></entry> + <entry>print/libgnomeprint</entry> + <entry>Biblioteca de suporte de impressão do Gnome 2</entry> + </row> + + <row> + <entry><literal>libgnomeprintui</literal></entry> + <entry>x11-toolkits/libgnomeprintui</entry> + <entry>Biblioteca de suporte de impressão do Gnome 2</entry> + </row> + + <row> + <entry><literal>libgnomeui</literal></entry> + <entry>x11-toolkits/libgnomeui</entry> + <entry>Bibliotecas para a GUI do GNOME 2, um ambiente de desktop GNU</entry> + </row> + + <row> + <entry><literal>libgtkhtml</literal></entry> + <entry>www/libgtkhtml</entry> + <entry>Mecanismo leve de renderização/impressão/edição de HTML</entry> + </row> + + <row> + <entry><literal>libgtksourceviewmm</literal></entry> + <entry>x11-toolkits/libgtksourceviewmm</entry> + <entry>c++ binding do GtkSourceView</entry> + </row> + + <row> + <entry><literal>libidl</literal></entry> + <entry>devel/libIDL</entry> + <entry>Biblioteca para criação de árvores de arquivo do CORBA IDL</entry> + </row> + + <row> + <entry><literal>libsigc++12</literal></entry> + <entry>devel/libsigc++12</entry> + <entry>Framework de Callback para C++</entry> + </row> + + <row> + <entry><literal>libwnck</literal></entry> + <entry>x11-toolkits/libwnck</entry> + <entry>Biblioteca usada para escrever pagers e listas de tarefas</entry> + </row> + + <row> + <entry><literal>libwnck3</literal></entry> + <entry>x11-toolkits/libwnck3</entry> + <entry>Biblioteca usada para escrever pagers e listas de tarefas</entry> + </row> + + <row> + <entry><literal>orbit2</literal></entry> + <entry>devel/ORBit2</entry> + <entry>CORBA ORB de alto desempenho com suporte para a linguagem C</entry> + </row> + + <row> + <entry><literal>pygnome2</literal></entry> + <entry>x11-toolkits/py-gnome2</entry> + <entry>Python bindings para GNOME 2</entry> + </row> + + <row> + <entry><literal>pygobject</literal></entry> + <entry>devel/py-gobject</entry> + <entry>Python 2, GObject 2.0 bindings</entry> + </row> + + <row> + <entry><literal>pygtk2</literal></entry> + <entry>x11-toolkits/py-gtk2</entry> + <entry>Conjunto de Python bindings para GTK+</entry> + </row> + + <row> + <entry><literal>pygtksourceview</literal></entry> + <entry>x11-toolkits/py-gtksourceview</entry> + <entry>Python bindings para GtkSourceView 2</entry> + </row> + + <row> + <entry><literal>vte</literal></entry> + <entry>x11-toolkits/vte</entry> + <entry>Widget de terminal com melhor acessibilidade e suporte I18N</entry> + </row> + </tbody> + </tgroup> + </table> + + <table xml:id="gnome-components-deprecated"> + <title>Componentes Obsoletos: Não Use</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Componente</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>pangox-compat</literal></entry> + <entry>O <application>pangox-compat</application>foi descontinuado e separado do pacote <application>pango</application>.</entry> + </row> + + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 xml:id="using-qt"> + <title>Usando o Qt</title> + + <sect2 xml:id="qt-common"> + <title>Ports que requerem o Qt</title> + + <para>A coleção de Ports fornece suporte para os frameworks Qt 4 e Qt 5 com <varname>USE_QT<replaceable>x</replaceable></varname>, onde <replaceable>x</replaceable> é <literal>4</literal> ou <literal>5</literal>. Defina <varname>USE_QT<replaceable>x</replaceable></varname> para a lista de componentes obrigatórios do Qt (bibliotecas, ferramentas, plugins). As estruturas do Qt 4 e Qt 5 são bastante semelhantes. A principal diferença é o conjunto de componentes suportados.</para> + + <para>O framework Qt exporta um número de variáveis que podem ser usadas por ports, algumas delas listadas abaixo:</para> + + <table frame="none" xml:id="using-qt-variables"> + <title>Variáveis Fornecidas aos Ports Que Usam o Qt</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><varname>QT_PREFIX</varname></entry> + <entry>Defina para o caminho onde o Qt foi instalado (<literal>${LOCALBASE}</literal>) </entry> + </row> + + <row> + <entry><varname>QMAKE</varname></entry> + <entry>Caminho completo para o binário <command>qmake</command>.</entry> + </row> + + <row> + <entry><varname>LRELEASE</varname></entry> + <entry>Caminho completo para utilitário <command>Irelease</command>.</entry> + </row> + + <row> + <entry><varname>MOC</varname></entry> + <entry>Caminho completo para <command>moc</command></entry> + </row> + + <row> + <entry><varname>RCC</varname></entry> + <entry>Caminho completo para <command>rcc</command></entry> + </row> + + <row> + <entry><varname>UIC</varname></entry> + <entry>Caminho completo para <command>uic</command></entry> + </row> + + <row> + <entry><varname>QT_INCDIR</varname></entry> + <entry>Diretório include Qt.</entry> + </row> + + <row> + <entry><varname>QT_LIBDIR</varname></entry> + <entry>Caminho das bibliotecas Qt.</entry> + </row> + + <row> + <entry><varname>QT_PLUGINDIR</varname></entry> + <entry>Caminho de plugins do Qt.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Ao usar o framework Qt, estas configurações são implementadas:</para> + + <programlisting>CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \ + --with-qt-libraries=${QT_LIBDIR} \ + --with-extra-libs=${LOCALBASE}/lib \ + --with-extra-includes=${LOCALBASE}/include + +CONFIGURE_ENV+= QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \ + MOC="${MOC}" RCC="${RCC}" UIC="${UIC}" \ + QMAKESPEC="${QMAKESPEC}" + +PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \ + QT_LIBDIR=${QT_LIBDIR_REL} \ + QT_PLUGINDIR=${QT_PLUGINDIR_REL}</programlisting> + + <para>Alguns scripts de configuração não suportam os argumentos acima. Para suprimir a modificação de <varname>CONFIGURE_ENV</varname> e <varname>CONFIGURE_ARGS</varname> defina <varname>QT_NONSTANDARD</varname>.</para> + </sect2> + + <sect2 xml:id="qt-components"> + <title>Seleção de Componentes</title> + + <para>Dependências individuais de ferramentas e bibliotecas do Qt devem ser especificadas em <varname>USE_QT<replaceable>x</replaceable></varname>. Cada componente pode ser sufixado com <literal>_build</literal> ou <literal>_run</literal>, o sufixo indica se a dependência no componente está no buildtime ou no runtime. Se não tiver o sufixo, o componente dependerá de ambos, buildtime e runtime. Normalmente, os componentes da biblioteca são especificados sem sufixo, os componentes da ferramenta são principalmente especificados com os sufixos <literal>_build</literal> e componentes do plugin são especificados com o sufixo <literal>_run</literal>. Os componentes mais usados estão listados abaixo (todos os componentes disponíveis estão listados em <varname>_USE_QT_ALL</varname>, <varname>_USE_QT4_ONLY</varname> e <varname>_USE_QT5_ONLY</varname> no arquivo <filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para> + + <table frame="none" xml:id="using-qt-library-list"> + <title>Componentes da Biblioteca Qt Disponíveis</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>core</literal></entry> + <entry>biblioteca principal (apenas Qt 5)</entry> + </row> + + <row> + <entry><literal>corelib</literal></entry> + <entry>core library (apenas Qt 4)</entry> + </row> + + <row> + <entry><literal>dbus</literal></entry> + <entry>Biblioteca Qt DBus</entry> + </row> + + <row> + <entry><literal>gui</literal></entry> + <entry>biblioteca de interface gráfica do usuário</entry> + </row> + + <row> + <entry><literal>network</literal></entry> + <entry>biblioteca de rede</entry> + </row> + + <row> + <entry><literal>opengl</literal></entry> + <entry>Biblioteca Qt OpenGL</entry> + </row> + + <row> + <entry><literal>script</literal></entry> + <entry>biblioteca de scripts</entry> + </row> + + <row> + <entry><literal>sql</literal></entry> + <entry>Biblioteca SQL</entry> + </row> + + <row> + <entry><literal>testlib</literal></entry> + <entry>biblioteca de testes unitários</entry> + </row> + + <row> + <entry><literal>webkit</literal></entry> + <entry>Biblioteca Qt WebKit</entry> + </row> + + <row> + <entry><literal>xml</literal></entry> + <entry>Biblioteca XML do Qt</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Para determinar as bibliotecas das quais um aplicativo depende, execute o <command>ldd</command> no executável principal após uma compilação bem sucedida. </para> + + <table frame="none" xml:id="using-qt-tools-list"> + <title>Componentes Disponíveis da Ferramenta Qt </title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>qmake</literal></entry> + <entry>Utilitário gerador/compilador de Makefile</entry> + </row> + + <row> + <entry><literal>buildtools</literal></entry> + <entry>Ferramentas de compilação (<command>moc</command>, <command>rcc</command>), necessária para quase todas as aplicações do Qt (apenas no Qt 5) </entry> + </row> + + <row> + <entry><literal>linguisttools</literal></entry> + <entry>ferramentas de localização: <command>Irelease</command>, <command>lupdate</command> (Apenas Qt 5) </entry> + </row> + + <row> + <entry><literal>linguist</literal></entry> + <entry>ferramentas de localização: <command>Irelease</command>, <command>lupdate</command> (Apenas Qt 4) </entry> + </row> + + <row> + <entry><literal>moc</literal></entry> + <entry>meta compilador de objeto, necessário para quase todos os aplicativos Qt no buildtime (apenas no Qt 4)</entry> + </row> + + <row> + <entry><literal>rcc</literal></entry> + <entry>compilador de recursos, necessário se o aplicativo vier com arquivos <filename>*.rc</filename> ou <filename>*.qrc </filename> (apenas Qt 4) </entry> + </row> + + <row> + <entry><literal>uic</literal></entry> + <entry>compilador de interface de usuário, necessário se o aplicativo vier com arquivos <filename>*.ui</filename>, na prática, todo aplicativo Qt com uma GUI (apenas Qt 4)</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" xml:id="using-qt-plugins-list"> + <title>Componentes Disponíveis de Plugin Qt </title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>iconengines</literal></entry> + <entry>Plugin de mecanismo de ícone SVG, necessário se o aplicativo contiver ícones SVG (apenas Qt 4)</entry> + </row> + + <row> + <entry><literal>imageformats</literal></entry> + <entry>plugins para formatos de imagem TGA, TIFF e MNG</entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="qt4-components-example"> + <title>Selecionando Componentes do Qt 4</title> + + <para>Neste exemplo, o aplicativo portado usa a biblioteca de interface gráfica do usuário do Qt 4, a biblioteca principal do Qt 4, todas as ferramentas de geração de código do Qt 4 e o gerador de Makefile do Qt 4. Uma vez que a biblioteca <literal>gui</literal> implica na dependência da biblioteca principal, o <literal>corelib</literal> não precisa ser especificado. As ferramentas de geração de código do Qt 4 <literal>moc</literal>, <literal>uic</literal> e <literal>rcc</literal>, bem como o gerador de Makefile <literal>qmake</literal> são necessários apenas no buildtime, assim eles são especificados com o sufixo <literal>_build</literal>:</para> + + <programlisting>USE_QT4= gui moc_build qmake_build rcc_build uic_build</programlisting> + </example> + </sect2> + + <sect2 xml:id="using-qmake"> + <title>Usando <command>qmake</command></title> + + + <para>Se o aplicativo fornecer um arquivo de projeto <application>qmake</application> (<filename>*.pro</filename>), defina <literal>USES=qmake</literal> junto com <literal>USE_QT<replaceable>x</replaceable></literal>. Observe que <literal>USES=qmake</literal> já implica uma dependência de compilação no qmake, portanto, o componente qmake pode ser omitido de <literal>USE_QT<replaceable>x</replaceable></literal>. Igual ao <link linkend="using-cmake"><application>CMake</application></link>, o <application>qmake</application> suporta compilações out-of-source, que podem ser ativadas especificando o argumento <literal>outsource</literal> (ver<link linkend="using-qmake-example"><literal>USES=qmake</literal>exemplo</link>) .</para> + + <table frame="none" xml:id="using-qmake-variables"> + <title>Variáveis para Ports Que Usam o <command>qmake</command></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Significa</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>QMAKE_ARGS</varname></entry> + <entry>Flags específicas do port <application>qmake</application> a serem passadas para o binario do <command>qmake</command>.</entry> + </row> + + <row> + <entry><varname>QMAKE_ENV</varname></entry> + <entry>Variáveis de ambiente a serem definidas para o binario <command>qmake</command>. O padrão é <literal>${CONFIGURE_ENV}</literal>.</entry> + </row> + + <row> + <entry><varname>QMAKE_SOURCE_PATH</varname></entry> + + <entry>Caminho para os arquivos de projeto do qmake (<filename>.pro</filename>). O padrão é <literal>${WRKSRC}</literal> se uma compilação out-of-source for solicitada, caso contrário, deixe em branco. </entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="using-qmake-example"> + <title>Exemplo <literal>USES= qmake</literal></title> + + <para>Este trecho demonstra o uso do <application>qmake</application> para um port Qt 4: </para> + + <programlisting>USES= qmake:outsource +USE_QT4= moc_build</programlisting> + + <para>Para um port Qt 5:</para> + <programlisting>USES= qmake:outsource +USE_QT5= buildtools_build</programlisting> + </example> + + <para>Aplicações Qt são frequentemente escritas para serem multi-plataforma e muitas vezes o X11/Unix não é a plataforma em que são desenvolvidas, o que por sua vez leva a certas pontas soltas, como:</para> + + <itemizedlist> + <listitem> + <para><emphasis>Faltam caminhos de inclusão adicionais.</emphasis> Muitos aplicativos vêm com suporte ao ícone da bandeja do sistema, mas não buscam inclusões e/ou bibliotecas nos diretórios do X11. Para adicionar diretórios aos includes e bibliotecas de pesquisa do <command>qmake</command> através da linha de comando, use:</para> + + <programlisting>QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ + LIBS+=-L${LOCALBASE}/lib</programlisting> + </listitem> + + <listitem> + <para><emphasis>Caminhos falsos de instalação.</emphasis> Às vezes, dados como ícones ou arquivos .desktop são instalados por padrão em diretórios que não são verificados por aplicativos compatíveis com XDG. O <package role="port">editors/texmaker</package> é um exemplo disso - veja <filename>patch-texmaker.pro</filename> no diretório de <filename>arquivos</filename> desse port para um modelo sobre como remediar isso diretamente no arquivo de projeto <command>qmake</command>.</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 xml:id="using-kde"> + <title>Usando o KDE</title> + + <sect2 xml:id="kde4-variables"> + <title>Definições de Variáveis do KDE 4</title> + + <para>Se a aplicação depender do KDE4, defina <literal>USES+=kde:4</literal> e <varname>USE_KDE</varname> à lista de componentes necessários. Sufixos <literal>_build</literal> e <literal>_run</literal> podem ser usados para forçar o tipo de dependência de componentes (por exemplo, <literal>baseapps_run</literal>). Se nenhum sufixo for definido, um tipo de dependência padrão será usado. Para forçar os dois tipos, adicione o componente duas vezes com os dois sufixos (por exemplo, <literal>automoc4_build automoc4_run</literal>). Os componentes mais usados são listados abaixo (os componentes atualizados são documentados no topo <filename>/usr/ports/Mk/bsd.kde4.mk</filename>): </para> + + <table frame="none" xml:id="using-kde-components"> + <title>Componentes Disponíveis do KDE 4</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>kdehier</literal></entry> + <entry>Hierarquia de diretórios comuns do KDE</entry> + </row> + + <row> + <entry><literal>kdelibs</literal></entry> + <entry>Bibliotecas principais do KDE</entry> + </row> + + <row> + <entry><literal>kdeprefix</literal></entry> + <entry>Se configurado, o port será instalado em <literal>${KDE_PREFIX}</literal></entry> + </row> + + <row> + <entry><literal>automoc4</literal></entry> + <entry>Ferramenta de compilação para gerar automaticamente arquivos moc</entry> + </row> + + <row> + <entry><literal>akonadi</literal></entry> + <entry>Servidor de armazenamento para dados do KDE PIM</entry> + </row> + + <row> + <entry><literal>soprano</literal></entry> + <entry>Biblioteca para o Resource Description Framework (RDF)</entry> + </row> + + <row> + <entry><literal>strigi</literal></entry> + <entry>Biblioteca de busca Strigi desktop</entry> + </row> + + <row> + <entry><literal>libkcddb</literal></entry> + <entry>Biblioteca do KDE CDDB (banco de dados de discos compactos)</entry> + </row> + + <row> + <entry><literal>libkcompactdisc</literal></entry> + <entry>Biblioteca do KDE para interfaceamento com CDs de áudio</entry> + </row> + + <row> + <entry><literal>libkdeedu</literal></entry> + <entry>Bibliotecas usadas por aplicativos educacionais</entry> + </row> + + <row> + <entry><literal>libkdcraw</literal></entry> + <entry>Biblioteca LibRaw do KDE</entry> + </row> + + <row> + <entry><literal>libkexiv2</literal></entry> + <entry>Biblioteca do KDE Exiv2</entry> + </row> + + <row> + <entry><literal>libkipi</literal></entry> + <entry>Interface de Plugin de Imagem do KDE</entry> + </row> + + <row> + <entry><literal>libkonq</literal></entry> + <entry>Biblioteca principal do Konqueror</entry> + </row> + + <row> + <entry><literal>libksane</literal></entry> + <entry>Biblioteca KDE SANE ("Scanner Access Now Easy")</entry> + </row> + + <row> + <entry><literal>pimlibs</literal></entry> + <entry>Bibliotecas de gerenciamento de informações pessoais</entry> + </row> + + <row> + <entry><literal>kate</literal></entry> + <entry>Framework avançado de editor de texto</entry> + </row> + + <row> + <entry><literal>marble</literal></entry> + <entry>Globo virtual e atlas mundial</entry> + </row> + + <row> + <entry><literal>okular</literal></entry> + <entry>Visualizador universal de documentos</entry> + </row> + + <row> + <entry><literal>korundum</literal></entry> + <entry>KDE Ruby bindings</entry> + </row> + + <row> + <entry><literal>perlkde</literal></entry> + <entry>KDE Perl bindings</entry> + </row> + + <row> + <entry><literal>pykde4</literal></entry> + <entry>KDE Python bindings</entry> + </row> + + <row> + <entry><literal>pykdeuic4</literal></entry> + <entry>Compilador de interface de usuário do PyKDE</entry> + </row> + + <row> + <entry><literal>smokekde</literal></entry> + <entry>Bibliotecas do KDE SMOKE</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Os ports do KDE 4 são instalados em <varname>KDE_PREFIX</varname>. Isto acontece especificando o componente <literal>kdeprefix</literal>, que substitui o padrão <varname>PREFIX</varname>. Os ports, no entanto, respeitam qualquer <varname>PREFIX</varname> definido através de uma variável de ambiente <envar>MAKEFLAGS</envar> e/ou argumentos <command>make</command>. Atualmente <varname>KDE_PREFIX</varname> é idêntico ao padrão <varname>PREFIX</varname>, <literal>${LOCALBASE}</literal>.</para> + + <example xml:id="kde4-components-example"> + <title>Exemplo <varname>USE_KDE</varname></title> + + <para>Este é um exemplo simples para um port do KDE 4. <literal>USES=cmake:outsource</literal> instrui o port a utilizar o <application>CMake</application>, uma ferramenta de configuração amplamente usada pelos projetos do KDE 4 (veja <xref linkend="using-cmake"/>para uso detalhado). <varname>USE_KDE</varname> traz dependência nas bibliotecas do KDE e compila o port usando <command>automoc4</command> no estágio de compilação. Os componentes necessários do KDE e outras dependências podem ser determinadas através do log de configuração. <varname>USE_KDE</varname> não implica no <varname>USE_QT4</varname>. Se um port requer alguns componentes do Qt 4, especifique-os em <varname>USE_QT4</varname>.</para> + + <programlisting>USES= cmake:outsource kde:4 +USE_KDE= kdelibs kdeprefix automoc4 +USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> + </example> + </sect2> + </sect1> + + <sect1 xml:id="using-lxqt"> + <title>Usando o LXQt</title> + + <para>As aplicações que dependem do LXQt devem definir <literal>USES+= lxqt</literal> e definir a variável <varname>USE_LXQT</varname> para a lista de componentes necessários da tabela abaixo </para> + + <table frame="none" xml:id="using-lxqt-components"> + <title>Componentes disponíveis do LXQt</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>buildtools</literal></entry> + <entry>Auxiliares para módulos CMake adicionais</entry> + </row> + + <row> + <entry><literal>libfmqt</literal></entry> + <entry>Libfm Qt bindings</entry> + </row> + + <row> + <entry><literal>lxqt</literal></entry> + <entry>LXQt core library</entry> + </row> + + <row> + <entry><literal>qtxdg</literal></entry> + <entry>Implementação do Qt das especificações do XDG do freedesktop.org</entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="lxqt-components-example"> + <title>Exemplo <literal>USE_LXQT</literal></title> + + <para>Este é um exemplo simples, <literal>USE_LXQT</literal> adiciona uma dependência em bibliotecas LXQt. Os componentes necessários do LXQt e outras dependências podem ser determinados a partir do log de configuração. </para> + <programlisting>USES= cmake:outsource lxqt tar:xz +USE_QT5= buildtools_build qmake_build core dbus widgets +USE_LXQT= buildtools libfmqt</programlisting> + </example> + </sect1> + + <sect1 xml:id="using-java"> + <title>Usando Java</title> + + <sect2 xml:id="java-variables"> + <title>Definições de Variáveis</title> + + <para>Se o port precisar de um Java™ Development Kit (<acronym>JDK</acronym>) para compilar, executar ou até mesmo extrair o distfile, então defina <varname>USE_JAVA</varname>.</para> + + <para>Existem vários <acronym>JDKs</acronym> na coleção de ports, de vários fornecedores e em várias versões. Se o port precisar usar uma versão específica, especifique-a usando a variável <varname>JAVA_VERSION</varname>. A versão mais atual é <package role="port">java/openjdk8</package>, <package role="port">java/openjdk6</package> e <package role="port">java/openjdk7</package> também estão disponíveis.</para> + + <table frame="none" xml:id="using-java-variables"> + <title>Variáveis Que Podem ser Definidas por Ports Que Usam Java</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Significa</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>USE_JAVA</varname></entry> + <entry>Defina para as variáveis restantes para ter algum efeito.</entry> + </row> + + <row> + <entry><varname>JAVA_VERSION</varname></entry> + <entry>Lista das versões Java adequadas separadas por espaço para o port. Um opcional <literal>"+"</literal> permite especificar um intervalo de versões (valores permitidos: <literal>1.5[+] 1.6[+] 1.7[+]</literal>).</entry> + </row> + + <row> + <entry><varname>JAVA_OS</varname></entry> + <entry>Lista de sistemas operacionais adequados do port <acronym>JDK</acronym> separados por espaço para o port (valores permitidos: <literal>native linux</literal>) </entry> + </row> + + <row> + <entry><varname>JAVA_VENDOR</varname></entry> + <entry>Lista de fornecedores adequados de ports <acronym>JDK</acronym> separados por espaços para o port (valores permitidos: <literal>freebsd bsdjava sun openjdk</literal>) </entry> + </row> + + <row> + <entry><varname>JAVA_BUILD</varname></entry> + <entry>Quando definido, adiciona o port <acronym>JDK</acronym> selecionado às dependências de compilação.</entry> + </row> + + <row> + <entry><varname>JAVA_RUN</varname></entry> + <entry>Quando definido, adicione o port <acronym>JDK</acronym> selecionado às dependências de execução.</entry> + </row> + + <row> + <entry><varname>JAVA_EXTRACT</varname></entry> + <entry>Quando definido, adicione o port <acronym>JDK</acronym> selecionado às dependências de extração.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Abaixo está a lista de todas as configurações que um port receberá após a configuração de <varname>USE_JAVA</varname>: </para> + + <table frame="none" xml:id="using-java-variables2"> + <title>Variáveis Fornecidas para Ports que Usam Java</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Valor</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>JAVA_PORT</varname></entry> + <entry>O nome do port do <acronym>JDK</acronym> (por exemplo,<literal>java/openjdk6</literal>) </entry> + </row> + + <row> + <entry><varname>JAVA_PORT_VERSION</varname></entry> + <entry>A versão completa do port do <acronym>JDK</acronym> (por exemplo,<literal>1.6.0</literal>). Somente os dois primeiros dígitos deste número de versão são necessários, use <varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname></entry> + </row> + + <row> + <entry><varname>JAVA_PORT_OS</varname></entry> + <entry>O sistema operacional usado pelo port do <acronym>JDK</acronym> (por exemplo, <literal>'native'</literal>) </entry> + </row> + + <row> + <entry><varname>JAVA_PORT_VENDOR</varname></entry> + <entry>O fornecedor do port <acronym>JDK</acronym> (por exemplo,<literal>'openjdk'</literal>) </entry> + </row> + + <row> + <entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry> + <entry>Descrição do sistema operacional usado pelo port <acronym>JDK</acronym> (por exemplo, <literal>'Native'</literal>) </entry> + </row> + + <row> + <entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry> + <entry>Descrição do fornecedor do port <acronym>JDK</acronym> (por exemplo,<literal>'OpenJDK BSD Porting Team'</literal>) </entry> + </row> + + <row> + <entry><varname>JAVA_HOME</varname></entry> + <entry>Caminho para o diretório de instalação do <acronym>JDK</acronym> (por exemplo, <filename>'/usr/local/openjdk6'</filename>) </entry> + </row> + + <row> + <entry><varname>JAVAC</varname></entry> + <entry>Caminho para o compilador Java (por exemplo, <filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry> + </row> + + <row> + <entry><varname>JAR</varname></entry> + <entry>Caminho para ferramenta <command>jar</command> a ser usada (por exemplo, <filename>'/usr/local/openjdk6/bin/jar'</filename> ou <filename>'/usr/local/bin/fastjar'</filename>).</entry> + </row> + + <row> + <entry><varname>APPLETVIEWER</varname></entry> + <entry>Caminho para o utilitário <command>appletviewer</command> (por exemplo,<filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry> + </row> + + <row> + <entry><varname>JAVA</varname></entry> + <entry>Caminho para o executável <command>Java</command>. Use isto para executar programas Java (por exemplo, <filename>'/usr/local/openjdk6/bin/java'</filename>).</entry> + </row> + + <row> + <entry><varname>JAVADOC</varname></entry> + <entry>Caminho para o utilitário <command>javadoc</command>.</entry> + </row> + + <row> + <entry><varname>JAVAH</varname></entry> + <entry>Caminho para o programa <command>javah</command>.</entry> + </row> + + <row> + <entry><varname>JAVAP</varname></entry> + <entry>Caminho para o programa <command>javap</command>.</entry> + </row> + + <row> + <entry><varname>JAVA_KEYTOOL</varname></entry> + <entry>Caminho para o utilitário <command>keytool</command>.</entry> + </row> + + <row> + <entry><varname>JAVA_N2A</varname></entry> + <entry>Caminho para a ferramenta <command>native2ascii</command>.</entry> + </row> + + <row> + <entry><varname>JAVA_POLICYTOOL</varname></entry> + <entry>Caminho para o programa <command>policytool</command>.</entry> + </row> + + <row> + <entry><varname>JAVA_SERIALVER</varname></entry> + <entry>Caminho para o utilitário <command>serialver</command>.</entry> + </row> + + <row> + <entry><varname>RMIC</varname></entry> + <entry>Caminho para o gerador de stub/skeleton RMI, <command>rmic</command>.</entry> + </row> + + <row> + <entry><varname>RMIREGISTRY</varname></entry> + <entry>Caminho para o programa de registro RMI, <command>rmiregistry</command>.</entry> + </row> + + <row> + <entry><varname>RMID</varname></entry> + <entry>Caminho para o daemon do RMI <command>rmid</command>.</entry> + </row> + + <row> + <entry><varname>JAVA_CLASSES</varname></entry> + <entry>Caminho para o arquivo que contém os arquivos de classe do <acronym>JDK</acronym>, <filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Use o <buildtarget>java-debug</buildtarget> make target para obter informações para depurar o port. Ele exibirá o valor de muitas das variáveis listadas anteriormente.</para> + + <para>Além disso, essas constantes são definidas para que todos os ports Java possam ser instalados de maneira consistente:</para> + + <table frame="none" xml:id="using-java-constants"> + <title>Constantes definidas para os ports que usam Java</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Constante</entry> + <entry>Valor</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>JAVASHAREDIR</varname></entry> + <entry>O diretório base para tudo relacionado ao Java. Padrão: <filename>${PREFIX}/share/java</filename>.</entry> + </row> + + <row> + <entry><varname>JAVAJARDIR</varname></entry> + <entry>O diretório onde os arquivos JAR são instalados. Padrão: <filename>${JAVASHAREDIR}/classes</filename>.</entry> + </row> + + <row> + <entry><varname>JAVALIBDIR</varname></entry> + <entry>O diretório onde os arquivos JAR instalados por outros ports estão localizados. Padrão: <filename>${LOCALBASE}/share/java/classes</filename>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>As entradas relacionadas são definidas em ambos <varname>PLIST_SUB</varname> (documentado em <xref linkend="plist-sub"/>) e <varname>SUB_LIST</varname>.</para> + </sect2> + + <sect2 xml:id="java-building-with-ant"> + <title>Compilando com Ant</title> + + <para>Quando o port deve ser compilado usando o Apache Ant, ele deve definir <varname>USE_ANT</varname>. Ant é, portanto, considerado o comando sub-make. Quando nenhum target <buildtarget>do-build</buildtarget> é definido pelo port, será definido um padrão que execute Ant de acordo com <varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname> e <varname>ALL_TARGET</varname>. Isso é semelhante ao mecanismo <literal>USES=gmake</literal>, documentado em <xref linkend="building"/>.</para> + </sect2> + + <sect2 xml:id="java-best-practices"> + <title>Melhores Práticas</title> + + <para>Ao portar uma biblioteca Java, o port precisa instalar o(s) arquivo(s) JAR em <filename>${JAVAJARDIR}</filename> e o resto em <filename>${JAVASHAREDIR}/${PORTNAME}</filename> (exceto para a documentação, veja abaixo). Para reduzir o tamanho do arquivo de empacotamento, faça referência aos arquivos JAR diretamente no <filename>Makefile</filename>. Use esta declaração (onde <filename> <replaceable>myport</replaceable>.jar</filename> é o nome do arquivo JAR instalado como parte do port): </para> + + <programlisting>PLIST_FILES+= ${JAVAJARDIR}/<replaceable>myport</replaceable>.jar</programlisting> + + <para>Ao portar um aplicativo Java, o port geralmente instala tudo em um único diretório (incluindo suas dependências JAR). O uso de <filename>${JAVASHAREDIR}/${PORTNAME}</filename> é fortemente indicado neste caso. Cabe ao mantenedor do port decidir se o port instala as dependências JAR adicionais sob esse diretório ou utiliza as já instaladas (de <filename>${JAVAJARDIR}</filename>).</para> + + <para>Ao portar um aplicativo <trademark>Java</trademark> que requer um servidor de aplicação, como o <package role="port">www/tomcat7</package> para executar o serviço, é bastante comum que o fornecedor distribua um <filename>.war</filename>. Um <filename>.war</filename> é uma aplicação Web ARchive a qual é extraído quando chamado pelo aplicativo. Evite adicionar um <filename>.war</filename> no <filename>pkg-plist</filename>. Isto não é considerado a melhor prática. Um servidor de aplicação irá expandir o arquivo <application>war</application> mas não irá remove-lo se o port for desinstalado. Uma forma mais desejável de trabalhar com este arquivo é extrair o seu conteudo, depois instalar os arquivos e, por fim, adicionar esses arquivos ao <filename>pkg-plist</filename>.</para> + + <programlisting>TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0 +WEBAPPDIR= myapplication + +post-extract: + @${MKDIR} ${WRKDIR}/${PORTDIRNAME} + @${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME} + +do-install: + cd ${WRKDIR} && \ + ${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME} + cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}</programlisting> + + <para>Independentemente do tipo de port (biblioteca ou aplicativo), a documentação adicional é instalada na <link linkend="install-documentation">mesma localização</link> como para qualquer outro port. A ferramenta Javadoc é conhecida por produzir um conjunto diferente de arquivos, dependendo da versão do <acronym>JDK</acronym> utilizado. Para ports que não impõem o uso de um determinado <acronym>JDK</acronym>, é uma tarefa complexa especificar a lista de empacotamento (<filename>pkg-plist</filename>). Esta é uma razão pela qual os mantenedores de ports são fortemente encorajados a usar <varname>PORTDOCS</varname>. Além disso, mesmo se o conjunto de arquivos que serão gerados pelo <command>javadoc</command> puder ser previsto, o tamanho do <filename>pkg-plist</filename> resultante irá encorajar o uso do <varname>PORTDOCS</varname>.</para> + + <para>O valor padrão para <varname>DATADIR</varname> é <filename>${PREFIX}/share/${PORTNAME}</filename>. É uma boa ideia sobreescrever <varname>DATADIR</varname> para <filename>${JAVASHAREDIR}/${PORTNAME}</filename> para ports Java. De fato, <varname>DATADIR</varname> é automaticamente adicionado a <varname>PLIST_SUB</varname> (documentado em<xref linkend="plist-sub"/>) então use <literal>%%DATADIR%%</literal> diretamente em <filename>pkg-plist</filename>.</para> + + <para>Quanto à escolha de compilar ports Java a partir do código fonte ou instalar diretamente a partir de uma distribuição binária, não há política definida no momento da escrita deste livro. No entanto, os membros do <link xlink:href="https://www.freebsd.org/java/">Projeto Java do FreeBSD</link> encorajam os mantenedores de ports a terem seus ports compilados a partir do código fonte sempre que for possível.</para> + + <para>Todos os recursos que foram apresentados nesta seção são implementados em <filename>bsd.java.mk</filename>. Se o port precisar de suporte Java mais sofisticado, por favor, primeiro dê uma olhada no log do <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=log">bsd.java.mk no <application>Subversion</application></link> pois normalmente leva algum tempo para documentar os recursos mais recentes. Então, se o suporte necessário que estiver faltando for benéfico para muitos outros ports Java, sinta-se à vontade para discuti-lo na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-java">Lista de discussão do FreeBSD sobre Linguagem Java</link>.</para> + + <para>Embora haja uma categoria <literal>Java</literal> para PRs, isso refere-se ao esforço de portabilidade do <acronym>JDK</acronym> do projeto Java do FreeBSD. Portanto, envie o port Java na categoria <literal>ports</literal> como para qualquer outro port, a menos que o problema esteja relacionado a uma implementação do <acronym>JDK</acronym> ou ao <filename>bsd.java.mk</filename>.</para> + + <para>Da mesma forma, existe uma política definida sobre as <varname>CATEGORIAS</varname> de um port Java, que é detalhada em <xref linkend="makefile-categories"/>.</para> + </sect2> + </sect1> + + <sect1 xml:id="using-php"> + <title>Aplicações Web, Apache e PHP</title> + + <sect2 xml:id="using-apache"> + <title>Apache</title> + + <table frame="none" xml:id="using-apache-variables"> + <title>Variáveis para Ports Que Usam o Apache</title> + + <tgroup cols="2"> + <tbody> + + <row> + <entry><varname>USE_APACHE</varname></entry> + <entry>O port requer o Apache. Valores possíveis: <literal>yes</literal> (obtém qualquer versão), <literal>22</literal>, <literal>24</literal>, <literal>22 a 24</literal>, <literal>22+</literal>, etc. A versão padrão do APACHE é <literal>22</literal>. Mais detalhes estão disponíveis em <filename>ports/Mk/bsd.apache.mk</filename> e em <link xlink:href="https://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</link>.</entry> + </row> + + <row> + <entry><varname>APXS</varname></entry> + <entry>Caminho completo para o binário <command>apxs</command>. Pode ser modificado no port.</entry> + </row> + + <row> + <entry><varname>HTTPD</varname></entry> + <entry>Caminho completo para o binário <command>httpd</command>. Pode ser modificado no port.</entry> + </row> + + <row> + <entry><varname>APACHE_VERSION</varname></entry> + <entry>A versão da instalação atual do Apache (variável somente leitura). Esta variável só está disponível após a inclusão de <filename>bsd.port.pre.mk</filename>. Valores possíveis: <literal>22</literal>, <literal>24</literal>.</entry> + </row> + + <row> + <entry><varname>APACHEMODDIR</varname></entry> + <entry>Diretório para módulos Apache. Esta variável é automaticamente expandida em <filename>pkg-plist</filename>.</entry> + </row> + + <row> + <entry><varname>APACHEINCLUDEDIR</varname></entry> + <entry>Diretório para cabeçalhos Apache. Esta variável é automaticamente expandida em <filename>pkg-plist</filename>.</entry> + </row> + + <row> + <entry><varname>APACHEETCDIR</varname></entry> + <entry>Diretório para arquivos de configuração do Apache. Esta variável é automaticamente expandida em <filename>pkg-plist</filename>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" xml:id="using-apache-modules"> + <title>Variáveis Úteis para Portar Módulos do Apache</title> + + <tgroup cols="2"> + <tbody> + + <row> + <entry><varname>MODULENAME</varname></entry> + <entry>Nome do módulo. O valor padrão é <varname>PORTNAME</varname>. + Exemplo: <literal>mod_hello</literal></entry> + </row> + + <row> + <entry><varname>SHORTMODNAME</varname></entry> + <entry>Nome abreviado do módulo. Automaticamente derivado de <varname>MODULENAME</varname>, mas pode ser substituído. Exemplo: <literal>hello</literal></entry> + </row> + + <row> + <entry><varname>AP_FAST_BUILD</varname></entry> + <entry>Use o <command>apxs</command> para compilar e instalar o módulo. </entry> + </row> + + <row> + <entry><varname>AP_GENPLIST</varname></entry> + <entry>Também cria automaticamente um <filename>pkg-plist</filename>.</entry> + </row> + + <row> + <entry><varname>AP_INC</varname></entry> + <entry>Adiciona um diretório ao caminho de pesquisa de cabeçalhos durante a compilação.</entry> + </row> + + <row> + <entry><varname>AP_LIB</varname></entry> + <entry>Adiciona um diretório ao caminho de pesquisa de bibliotecas durante a compilação.</entry> + </row> + + <row> + <entry><varname>AP_EXTRAS</varname></entry> + <entry>Flags adicionais para passar para o <command>apxs</command>.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2 xml:id="web-apps"> + <title>Aplicações Web</title> + + <para>Aplicações web devem ser instaladas em <filename>PREFIX/www/<replaceable>appname</replaceable></filename>. Este caminho está disponível tanto no <filename>Makefile</filename> quanto no <filename>pkg-plist</filename> como <varname>WWWDIR</varname> e o caminho relativo para <varname>PREFIX</varname> está disponível no <filename>Makefile</filename> como <varname>WWWDIR_REL</varname>.</para> + + <para>O usuário e o grupo do processo do servidor web estão disponíveis como <varname>WWWOWN</varname> e <varname>WWWGRP</varname>, no caso de a propriedade de alguns arquivos precisar ser alterada. Os valores padrão de ambos são <literal>www</literal>. Use <literal>WWWOWN?=myuser</literal> e <literal>WWWGRP?=mygroup</literal> se o port precisar de valores diferentes. Isso permite ao usuário substituí-los facilmente. </para> + + <important> + <para>Use <varname>WWWOWN</varname> e <varname>WWWGRP</varname> com moderação. Lembre-se de que todos os arquivos para os quais o servidor web tem permissão de escrita, são um risco de segurança esperando para acontecer.</para> + </important> + + <para>Não insira o Apache como dependência, a menos que o aplicativo web precise explicitamente do Apache. Respeite que os usuários podem desejar executar um aplicativo web em um servidor web diferente do <application>Apache</application>.</para> + </sect2> + + <sect2 xml:id="php-variables"> + <title>PHP</title> + + <para>Aplicações <application>PHP</application> declaram sua dependência a ele com <literal>USES=php</literal>. Veja <xref linkend="uses-php"/> para maiores informações.</para> + </sect2> + + <sect2 xml:id="php-pear"> + <title>Módulos PEAR</title> + + <para>Portar módulos PEAR é um processo muito simples.</para> + + <para>Adicione <literal>USES=pear</literal> ao <filename>Makefile</filename> do port. O framework instalará os arquivos relevantes nos lugares certos e gerará automaticamente a lista no momento da instalação.</para> + + <example xml:id="pear-makefile"> + <title>Exemplo de Makefile para Classes PEAR</title> + + <programlisting>PORTNAME= Date +DISTVERSION= 1.4.3 +CATEGORIES= devel www pear + +MAINTAINER= example@domain.com +COMMENT= PEAR Date and Time Zone Classes + +USES= pear + +.include <bsd.port.mk></programlisting> + </example> + + <tip> + <para>Os módulos <application>PEAR</application> serão automaticamente flavorizados usando <link linkend="flavors-auto-php"><application>PHP</application>flavors</link>.</para> + </tip> + + <note> + <para>Se um <varname>PEAR_CHANNEL</varname> não padrão for usado, as dependências de compilação e de tempo de execução serão automaticamente adicionadas.</para> + </note> + + <important> + <para>Módulos PEAR não precisam definir <varname>PKGNAMESUFFIX</varname>, é preenchido automaticamente usando <varname>PEAR_PKGNAMEPREFIX</varname>. Se um port precisar adicionar <varname>PKGNAMEPREFIX</varname>, também deve usar <varname>PEAR_PKGNAMEPREFIX</varname> para diferenciar entre diferentes flavors.</para> + </important> + + <sect3 xml:id="php-horde"> + <title>Módulos <application>Horde</application></title> + + <para>Da mesma forma, portar módulos <application>Horde</application> é um processo simples.</para> + + <para>Adicione <literal>USES=horde</literal> ao <filename>Makefile</filename> do port . O framework instalará os arquivos relevantes nos lugares certos e gerará automaticamente a lista no momento da instalação. </para> + + <para>As variáveis <varname>USE_HORDE_BUILD</varname> e <varname>USE_HORDE_RUN</varname> podem ser usadas para adicionar dependências de tempo de compilação e de tempo de execução em outros módulos <application>Horde</application>. Veja <filename>Mk/Uses/horde.mk</filename> para uma lista completa dos módulos disponíveis. </para> + + <example xml:id="horde-Makefile"> + <title>Exemplo de Makefile para Módulos <application>Horde</application></title> + + <programlisting>PORTNAME= Horde_Core +DISTVERSION= 2.14.0 +CATEGORIES= devel www pear + +MAINTAINER= horde@FreeBSD.org +COMMENT= Horde Core Framework libraries + +OPTIONS_DEFINE= KOLAB SOCKETS +KOLAB_DESC= Enable Kolab server support +SOCKETS_DESC= Depend on sockets PHP extension + +USES= horde +USE_PHP= session + +USE_HORDE_BUILD= Horde_Role +USE_HORDE_RUN= Horde_Role Horde_History Horde_Pack \ + Horde_Text_Filter Horde_View + +KOLAB_USE= HORDE_RUN=Horde_Kolab_Server,Horde_Kolab_Session +SOCKETS_USE= PHP=sockets + +.include <bsd.port.mk></programlisting> + </example> + + <tip> + <para>Como os módulos <application>Horde</application> também são módulos <application>PEAR</application>, eles também serão automaticamente aromatizados usando <link linkend="flavors-auto-php"><application>PHP</application> flavors</link>.</para> + </tip> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="using-python"> + <title>Usando Python</title> + + <para>A Coleção de Ports suporta a instalação paralela de várias versões do Python. Os ports devem usar um interpretador <command>python</command>, de acordo com a configuração do usuário de <varname>PYTHON_VERSION</varname>. Mais proeminentemente, isso significa substituir o caminho para o executável <command>python</command> em scripts com o valor de <varname>PYTHON_CMD</varname>.</para> + + <para>Ports que instalam arquivos sob <varname>PYTHON_SITELIBDIR</varname> devem usar o prefixo <literal>pyXY-</literal> no prefixo do nome do pacote, assim o nome do pacote irá incorporar a versão do Python em que estão instalados. </para> + + <programlisting>PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX}</programlisting> + + <table frame="none" xml:id="using-python-variables"> + <title>Variáveis úteis para Ports que usam Python</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><varname>USES=python</varname></entry> + <entry>O port precisa do Python. A versão mínima necessária pode ser especificada com valores como <literal>2.7+</literal>. Os intervalos de versão também podem ser especificados separando dois números de versão com um traço: <literal>USES=python:3.2-3.3</literal></entry> + </row> + + <row> + <entry><varname>USE_PYTHON=distutils</varname></entry> + <entry>Use o distutils do Python para configurar, compilar e instalar. Isso é necessário quando o port vem com <filename>setup.py</filename>. Isso sobrescreve os targets <buildtarget>do-build</buildtarget> e <buildtarget>do-install</buildtarget> e também pode substituir <buildtarget>do-configure</buildtarget> se o <varname>GNU_CONFIGURE</varname> não estiver definido. Além disso, isso implica em <literal>USE_PYTHON=flavors</literal>.</entry> + </row> + + <row> + <entry><varname>USE_PYTHON=autoplist</varname></entry> + <entry>Crie a lista de empacotamento automaticamente. Isso também requer que <literal>USE_PYTHON=distutils</literal> seja definido. </entry> + </row> + + <row> + <entry><varname>USE_PYTHON=concurrent</varname></entry> + <entry>O port usará um prefixo exclusivo, normalmente <literal>PYTHON_PKGNAMEPREFIX</literal> para determinados diretórios, como <literal>EXAMPLESDIR</literal> e <literal>DOCSDIR</literal> e também irá acrescentar um sufixo, a versão python de <literal>PYTHON_VER</literal>, para os binários e scripts que serão instalados. Isso permite que os ports sejam instalados para diferentes versões do Python ao mesmo tempo, o que de outra forma instalaria arquivos conflitantes. </entry> + </row> + + <row> + <entry><literal>USE_PYTHON=flavors</literal></entry> + <entry>O port não usa distutils, mas ainda suporta várias versões do Python. .<varname>FLAVORS</varname> será definido para as versões suportadas do Python. Veja <xref linkend="flavors-auto-python"/> para maiores informações.</entry> + </row> + + <row> + <entry><literal>USE_PYTHON=optsuffix</literal></entry> + <entry>Se a versão atual do Python não for a versão padrão, o port receberá <literal>PKGNAMESUFFIX=${PYTHON_PKGNAMESUFFIX}</literal>. É útil apenas com flavors.</entry> + </row> + + <row> + <entry><varname>PYTHON_PKGNAMEPREFIX</varname></entry> + <entry>Usado como um <varname>PKGNAMEPREFIX</varname> para distinguir pacotes para diferentes versões do Python. Exemplo: <literal>py27-</literal></entry> + </row> + + <row> + <entry><varname>PYTHON_SITELIBDIR</varname></entry> + <entry>Local da árvore site-packages, que contém o caminho de instalação do Python (geralmente <varname>LOCALBASE</varname>). A <varname>PYTHON_SITELIBDIR</varname> pode ser muito útil ao instalar módulos Python. </entry> + </row> + + <row> + <entry><varname>PYTHONPREFIX_SITELIBDIR</varname></entry> + <entry>A variante PREFIX-clean do PYTHON_SITELIBDIR. Sempre use <literal>%%PYTHON_SITELIBDIR%%</literal> no <filename>pkg-plist</filename> quando possível. O valor padrão de <literal>%%PYTHON_SITELIBDIR%%</literal> é <literal>lib/python%%PYTHON_VERSION%%/site-packages</literal></entry> + </row> + + <row> + <entry><varname>PYTHON_CMD</varname></entry> + <entry>Linha de comando do interpretador Python, incluindo o número da versão.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" xml:id="using-python-variables-helpers"> + <title>Assistentes do Módulo de Dependências do Python </title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><varname>PYNUMERIC</varname></entry> + <entry>Linha de dependência para extensão numérica.</entry> + </row> + + <row> + <entry><varname>PYNUMPY</varname></entry> + <entry>Linha de dependência para a nova extensão numérica, numpy. (PYNUMERIC foi descontinuado pelo fornecedor upstream).</entry> + </row> + + <row> + <entry><varname>PYXML</varname></entry> + <entry>Linha de dependência para a extensão XML (não é necessária para o Python 2.0 e superior, pois também está na distribuição base).</entry> + </row> + + <row> + <entry><varname>PY_ENUM34</varname></entry> + <entry>Dependência condicional do <package>devel/py-enum34</package> dependendo da versão do Python. </entry> + </row> + + <row> + <entry><varname>PY_ENUM_COMPAT</varname></entry> + <entry>Dependência condicional do <package>devel/py-enum-compat</package> dependendo da versão do Python.</entry> + </row> + + <row> + <entry><varname>PY_PATHLIB</varname></entry> + <entry>Dependência condicional do <package>devel/py-pathlib</package> dependendo da versão do Python.</entry> + </row> + + <row> + <entry><varname>PY_IPADDRESS</varname></entry> + <entry>Dependência condicional do <package>net/py-ipaddress</package> dependendo da versão do Python.</entry> + </row> + + <row> + <entry><varname>PY_FUTURES</varname></entry> + <entry>Dependência condicional do <package>devel/py-futures</package> dependendo da versão do Python.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Uma lista completa das variáveis disponíveis pode ser encontrada em <filename>/usr/ports/Mk/Uses/python.mk</filename></para> + + <important> + <para>Todas as dependências para ports <application>Python</application> usando <link linkend="flavors-auto-python"><application>Python</application> flavors</link> (quer com <literal>USE_PYTHON=distutils</literal> ou <literal>USE_PYTHON=flavors</literal>) deve ter o flavor Python anexado à sua origem usando <literal>@${PY_FLAVOR}</literal>. Veja <xref linkend="python-Makefile"/></para> + </important> + + <example xml:id="python-Makefile"> + <title>Makefile para um Módulo <application>Python</application> Simples.</title> + + <programlisting>PORTNAME= sample +DISTVERSION= 1.2.3 +CATEGORIES= devel + +MAINTAINER= john@doe.tld +COMMENT= Python sample module + +RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR} + +USES= python +USE_PYTHON= autoplist distutils + +.include <bsd.port.mk></programlisting> + </example> + + <para>Algumas aplicações Python afirmam ter suporte a <varname>DESTDIR</varname> (que seria necessário para fazer o staging), mas ele está quebrado (Mailman até a versão 2.1.16, por exemplo). Isso pode ser contornado, recompilando os scripts. Isso pode ser feito, por exemplo, no target <buildtarget>post-build</buildtarget>. Assumindo que os scripts Python devem estar em <varname>PYTHONPREFIX_SITELIBDIR</varname> após a instalação, esta solução pode ser aplicada: </para> + + <programlisting>(cd ${STAGEDIR}${PREFIX} \ + && ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \ + -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;})</programlisting> + + <para>Isso recompila os fontes com um caminho relativo ao diretório de stage e acrescenta o valor de <varname>PREFIX</varname> para o nome do arquivo gravado no arquivo bytecode de saída por <literal>-d</literal>. O <literal>-f</literal> é necessário para forçar a recompilação e o <literal>:S;${PREFIX}/;;</literal> remove prefixos do valor de <varname>PYTHONPREFIX_SITELIBDIR</varname> para torná-lo relativo ao <varname>PREFIX</varname>.</para> + </sect1> + + <sect1 xml:id="using-tcl"> + <title>Usando <application>Tcl/Tk</application></title> + + <para>A Coleção de Ports suporta a instalação paralela de múltiplas versões do <application>Tcl/Tk</application>. Ports devem tentar suportar pelo menos a versão padrão do <application>Tcl/Tk</application> e superior com <literal>USES=tcl</literal>. É possível especificar a versão desejada do <command>tcl</command> anexando <literal>:<replaceable>xx</replaceable></literal>, por exemplo, <literal>USES=tcl:85</literal>.</para> + + <table frame="none" xml:id="using-tcl-variables"> + <title>As variáveis read only muito úteis para Ports que usam <application>Tcl/Tk</application></title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><varname>TCL_VER</varname></entry> + <entry>versão major.minor escolhida do <application>Tcl</application></entry> + </row> + + <row> + <entry><varname>TCLSH</varname></entry> + <entry>caminho completo do interpretador <application>Tcl</application></entry> + </row> + + <row> + <entry><varname>TCL_LIBDIR</varname></entry> + <entry>caminho das bibliotecas <application>Tcl</application></entry> + </row> + + <row> + <entry><varname>TCL_INCLUDEDIR</varname></entry> + <entry>caminho dos arquivos de cabeçalho C do <application>Tcl</application></entry> + </row> + + <row> + <entry><varname>TK_VER</varname></entry> + <entry>versão major.minor escolhida do <application>Tk</application></entry> + </row> + + <row> + <entry><varname>WISH</varname></entry> + <entry>caminho completo do interpretador <application>Tk</application></entry> + </row> + + <row> + <entry><varname>TK_LIBDIR</varname></entry> + <entry>caminho das bibliotecas <application>Tk</application></entry> + </row> + + <row> + <entry><varname>TK_INCLUDEDIR</varname></entry> + <entry>caminho dos arquivos de cabeçalho C do <application>Tk</application></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Veja o <link linkend="uses-tcl"><literal>USES=tcl</literal></link> e <link linkend="uses-tk"><literal>USES=tk</literal></link> do <xref linkend="uses"/> para uma descrição completa dessas variáveis. Uma lista completa dessas variáveis está disponível em <filename>/usr/ports/Mk/Uses/tcl.mk</filename>.</para> + </sect1> + + <sect1 xml:id="using-ruby"> + <title>Usando Ruby</title> + + <table frame="none" xml:id="using-ruby-variables"> + <title>Variáveis Úteis para Ports Que Usam Ruby</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Descrição</entry> + </row> + </thead> + <tbody> + <row> + <entry><varname>USE_RUBY</varname></entry> + <entry>Adiciona dependências de build e run no Ruby.</entry> + </row> + + <row> + <entry><varname>USE_RUBY_EXTCONF</varname></entry> + <entry>O port utiliza <filename>extconf.rb</filename> para configurar.</entry> + </row> + + <row> + <entry><varname>USE_RUBY_SETUP</varname></entry> + <entry>O port utiliza <filename>setup.rb</filename> para configurar.</entry> + </row> + + <row> + <entry><varname>RUBY_SETUP</varname></entry> + <entry>Substitui o nome do script de configuração do <filename>setup.rb</filename>. Outro valor comum é <filename>install.rb</filename>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Esta tabela mostra as variáveis selecionadas disponíveis para os autores dos ports através da infraestrutura de ports. Essas variáveis são usadas para instalar arquivos em seus locais apropriados. Use-os em <filename>pkg-plist</filename> tanto quanto possível. Não redefina essas variáveis no port. </para> + + <table frame="none" xml:id="using-ruby-variables-ro"> + <title>Variáveis Somente Leitura Selecionadas para Ports Que Usam Ruby</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Variável</entry> + <entry>Descrição</entry> + <entry>Exemplo de valor</entry> + </row> + </thead> + <tbody> + + <row> + <entry><varname>RUBY_PKGNAMEPREFIX</varname></entry> + <entry>Usado como um <varname>PKGNAMEPREFIX</varname> para distinguir pacotes para diferentes versões do Ruby. </entry> + <entry><literal>ruby19-</literal></entry> + </row> + + <row> + <entry><varname>RUBY_VERSION</varname></entry> + <entry>Versão completa do Ruby na forma de <literal>x.y.z[.p]</literal>.</entry> + <entry><literal>1.9.3.484</literal></entry> + </row> + + <row> + <entry><varname>RUBY_SITELIBDIR</varname></entry> + <entry>Caminho de instalação de bibliotecas independentes de arquitetura.</entry> + <entry><literal>/usr/local/lib/ruby/site_ruby/1.9</literal></entry> + </row> + + <row> + <entry><varname>RUBY_SITEARCHLIBDIR</varname></entry> + <entry>Caminho de instalação das bibliotecas dependentes de arquitetura.</entry> + <entry><literal>/usr/local/lib/ruby/site_ruby/1.9/amd64-freebsd10</literal></entry> + </row> + + <row> + <entry><varname>RUBY_MODDOCDIR</varname></entry> + <entry>Caminho de instalação da documentação do módulo.</entry> + <entry><literal>/usr/local/share/doc/ruby19/patsy</literal></entry> + </row> + + <row> + <entry><varname>RUBY_MODEXAMPLESDIR</varname></entry> + <entry>Caminho de instalação dos exemplos do módulo.</entry> + <entry><literal>/usr/local/share/examples/ruby19/patsy</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Uma lista completa das variáveis disponíveis pode ser encontrada em <filename>/usr/ports/Mk/bsd.ruby.mk</filename>.</para> + </sect1> + + <sect1 xml:id="using-sdl"> + <title>Usando SDL</title> + + <para>O <varname>USE_SDL</varname> é usado para auto configurar as dependências para os ports que usam uma biblioteca baseada em SDL como o <package role="port">devel/sdl12</package> e o <package role="port">graphics/sdl_image</package>.</para> + + <para>Estas bibliotecas SDL para a versão 1.2 são reconhecidas:</para> + + <itemizedlist> + <listitem> + <para>sdl: <package role="port">devel/sdl12</package></para> + </listitem> + + <listitem> + <para>console: <package role="port">devel/sdl_console</package></para> + </listitem> + + <listitem> + <para>gfx: <package role="port">graphics/sdl_gfx</package></para> + </listitem> + + <listitem> + <para>image: <package role="port">graphics/sdl_image</package></para> + </listitem> + + <listitem> + <para>mixer: <package role="port">audio/sdl_mixer</package></para> + </listitem> + + <listitem> + <para>mm: <package role="port">devel/sdlmm</package></para> + </listitem> + + <listitem> + <para>net: <package role="port">net/sdl_net</package></para> + </listitem> + + <listitem> + <para>pango: <package role="port">x11-toolkits/sdl_pango</package></para> + </listitem> + + <listitem> + <para>sound: <package role="port">audio/sdl_sound</package></para> + </listitem> + + <listitem> + <para>ttf: <package role="port">graphics/sdl_ttf</package></para> + </listitem> + </itemizedlist> + + <para>Estas são as bibliotecas SDL para a versão 2.0 reconhecidas:</para> + + <itemizedlist> + <listitem> + <para>sdl: <package role="port">devel/sdl20</package></para> + </listitem> + + <listitem> + <para>gfx: <package role="port">graphics/sdl2_gfx</package></para> + </listitem> + + <listitem> + <para>image: <package role="port">graphics/sdl2_image</package></para> + </listitem> + + <listitem> + <para>mixer: <package role="port">audio/sdl2_mixer</package></para> + </listitem> + + <listitem> + <para>net: <package role="port">net/sdl2_net</package></para> + </listitem> + + <listitem> + <para>ttf: <package role="port">graphics/sdl2_ttf</package></para> + </listitem> + </itemizedlist> + + <para>Portanto, se um port tiver uma dependência do <package role="port">net/sdl_net</package> e do <package role="port">audio/sdl_mixer</package>, a sintaxe será: </para> + + <programlisting>USE_SDL= net mixer</programlisting> + + <para>A dependência <package role="port">devel/sdl12</package>, a qual é exigida por <package role="port">net/sdl_net</package> e <package role="port">audio/sdl_mixer</package>, é automaticamente adicionada também. </para> + + <para>Usar <varname>USE_SDL</varname> com entradas para o SDL 1.2, irá automaticamente:</para> + + <itemizedlist> + <listitem> + <para>Adicionar uma dependência em <application>sdl12-config</application> para <varname>BUILD_DEPENDS</varname></para> + </listitem> + + <listitem> + <para>Adicionar a variável <varname>SDL_CONFIG</varname> + em <varname>CONFIGURE_ENV</varname></para> + </listitem> + + <listitem> + <para>Adicionar as dependências das bibliotecas selecionadas ao <varname>LIB_DEPENDS</varname></para> + </listitem> + </itemizedlist> + + <para>Usar <varname>USE_SDL</varname> com entradas para o SDL 2.0, irá automaticamente: </para> + + <itemizedlist> + <listitem> + <para>Adicionar uma dependência em <application>sdl2-config</application> para <varname>BUILD_DEPENDS</varname></para> + </listitem> + + <listitem> + <para>Adicionar a variável <varname>SDL2_CONFIG</varname> + ao <varname>CONFIGURE_ENV</varname></para> + </listitem> + + <listitem> + <para>Adicionar as dependências das bibliotecas selecionadas ao <varname>LIB_DEPENDS</varname></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="using-wx"> + <title>Usando <application>wxWidgets</application></title> + + <para>Esta seção descreve o status das bibliotecas <application>wxWidgets</application> na árvore de ports e sua integração com o sistema de ports. </para> + + <sect2 xml:id="wx-introduction"> + <title>Introdução</title> + + <para>Existem muitas versões das bibliotecas do <application>wxWidgets</application> que entram em conflito entre elas (instalam arquivos com o mesmo nome). Na árvore de ports este problema foi resolvido instalando cada versão sob um nome diferente usando sufixos de número de versão. </para> + + <para>A desvantagem óbvia disso é que cada aplicativo precisa ser modificado para encontrar a versão esperada. Felizmente, a maioria dos aplicativos chama o script <command>wx-config</command> para determinar os sinalizadores necessários para o compilador e o vinculador. O script é nomeado de maneira diferente para cada versão disponível. A maioria dos aplicativos respeita uma variável de ambiente ou aceita um argumento de configuração para especificar o script <command>wx-config</command> que deve ser chamado. Caso contrário, eles têm que ser corrigidos.</para> + </sect2> + + <sect2 xml:id="wx-version"> + <title>Seleção de Versão</title> + + <para>Para fazer o port usar uma versão específica do <application>wxWidgets</application> existem duas variáveis disponíveis para definir (se apenas uma for definida, a outra será definida para um valor padrão): </para> + + <table xml:id="wx-ver-sel-table" frame="none"> + <title>Variáveis para Selecionar as Versões do <application>wxWidgets</application></title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Variável</entry> + <entry>Descrição</entry> + <entry>Valor padrão</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>USE_WX</varname></entry> + <entry>Lista de versões que o port pode usar</entry> + <entry>Todas as versões disponíveis</entry> + </row> + + <row> + <entry><varname>USE_WX_NOT</varname></entry> + <entry>Lista de versões que o port não pode usar</entry> + <entry>Nenhum</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>As versões disponíveis do <application>wxWidgets</application> e os ports correspondentes na árvore são: </para> + + <table frame="none" xml:id="wx-widgets-versions-table"> + <title>Versões Disponíveis do <application>wxWidgets</application></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Versão</entry> + <entry>Port</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>2.8</literal></entry> + <entry><package role="port">x11-toolkits/wxgtk28</package></entry> + </row> + + <row> + <entry><literal>3.0</literal></entry> + <entry><package role="port">x11-toolkits/wxgtk30</package></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>As variáveis em <xref linkend="wx-ver-sel-table"/> podem ser definidas para uma ou mais dessas combinações separadas por espaços:</para> + + <table frame="none" xml:id="wx-widgets-versions-specification"> + <title>Especificações de Versão do <application>wxWidgets</application> </title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Descrição</entry> + <entry>Exemplo</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Versão única</entry> + <entry><literal>2.8</literal></entry> + </row> + + <row> + <entry>Range ascendente</entry> + <entry><literal>2.8+</literal></entry> + </row> + + <row> + <entry>Range descendente</entry> + <entry><literal>3.0-</literal></entry> + </row> + + <row> + <entry>Range total (deve ser crescente)</entry> + <entry><literal>2.8-3.0</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Também existem algumas variáveis para selecionar as versões preferidas entre as disponíveis. Elas podem ser configuradas para uma lista de versões, as primeiras terão maior prioridade.</para> + + <table frame="none" xml:id="wx-widgets-preferred-version"> + <title>Variáveis para selecionar as versões preferidas do <application>wxWidgets</application> </title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Desenhado para</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>WANT_WX_VER</varname></entry> + <entry>o port</entry> + </row> + + <row> + <entry><varname>WITH_WX_VER</varname></entry> + <entry>o usuário</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2 xml:id="wx-components"> + <title>Seleção de Componentes</title> + + <para>Existem outras aplicações que, apesar de não serem bibliotecas <application>wxWidgets</application>, estão relacionadas a eles. Estas aplicações podem ser especificadas em <varname>WX_COMPS</varname>. Estes componentes estão disponíveis:</para> + + <table frame="none" xml:id="wx-widgets-components-table"> + <title>Componentes <application>wxWidgets</application> Disponíveis</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + <entry>Restrição de versão</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>wx</literal></entry> + <entry>biblioteca principal</entry> + <entry>nenhum</entry> + </row> + + <row> + <entry><literal>contrib</literal></entry> + <entry>bibliotecas contribuídas</entry> + <entry><literal>none</literal></entry> + </row> + + <row> + <entry><literal>python</literal></entry> + <entry><application>wxPython</application>(ligações <application>Python</application>)</entry> + <entry><literal>2.8-3.0</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>O tipo de dependência pode ser selecionado para cada componente, adicionando-se um sufixo separado por um ponto-e-vírgula. Se não estiver presente, será usado um tipo padrão (veja <xref linkend="wx-def-dep-types"/>). Estes tipos estão disponíveis:</para> + + <table frame="none" xml:id="wx-widgets-dependency-table"> + <title>Tipos de Dependências <application>wxWidgets</application> Disponíveis</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>build</literal></entry> + <entry>Componente é necessário para a compilação, equivalente a <varname>BUILD_DEPENDS</varname></entry> + </row> + + <row> + <entry><literal>run</literal></entry> + <entry>O componente é necessário para execução, equivalente a <varname>RUN_DEPENDS</varname></entry> + </row> + + <row> + <entry><literal>lib</literal></entry> + <entry>O componente é necessário para a compilação e execução, equivalente a <varname>LIB_DEPENDS</varname></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Os valores padrão para os componentes estão detalhados nesta tabela:</para> + + <table xml:id="wx-def-dep-types" frame="none"> + <title>Tipos de Dependência Padrão do <application>wxWidgets</application></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Componente</entry> + <entry>Tipo de dependência</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>wx</literal></entry> + <entry><literal>lib</literal></entry> + </row> + + <row> + <entry><literal>contrib</literal></entry> + <entry><literal>lib</literal></entry> + </row> + + <row> + <entry><literal>python</literal></entry> + <entry><literal>run</literal></entry> + </row> + + <row> + <entry><literal>mozilla</literal></entry> + <entry><literal>lib</literal></entry> + </row> + + <row> + <entry><literal>svg</literal></entry> + <entry><literal>lib</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="wx-components-example"> + <title>Selecionando Componentes <application>wxWidgets</application></title> + + <para>Este fragmento corresponde a um port que usa <application>wxWidgets</application> versão <literal>2.4</literal> e suas bibliotecas contribuídas.</para> + + <programlisting>USE_WX= 2.8 +WX_COMPS= wx contrib</programlisting> + </example> + </sect2> + + <sect2 xml:id="wx-version-detection"> + <title>Detectando Versões Instaladas</title> + + <para>Para detectar uma versão instalada, defina <varname>WANT_WX</varname>. Se não estiver definido para uma versão específica, os componentes terão um sufixo de versão. O <varname>HAVE_WX</varname> será preenchido após a detecção.</para> + + <example xml:id="wx-ver-det-example"> + <title>Detectando as versões instaladas <application>wxWidgets</application> e seus componentes</title> + + <para>Este fragmento pode ser usado em um port que usa <application>wxWidgets</application> se estiver instalado ou uma opção estiver selecionada.</para> + + <programlisting>WANT_WX= yes + +.include <bsd.port.pre.mk> + +.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.8) +USE_WX= 2.8 +CONFIGURE_ARGS+= --enable-wx +.endif</programlisting> + + <para>Este fragmento pode ser usado em um port que permite suporte ao <application>wxPython</application> se ele estiver instalado ou se uma opção for selecionada, em adição ao <application>wxWidgets</application>, ambas nas versões <literal>2.8</literal>.</para> + + <programlisting>USE_WX= 2.8 +WX_COMPS= wx +WANT_WX= 2.8 + +.include <bsd.port.pre.mk> + +.if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) +WX_COMPS+= python +CONFIGURE_ARGS+= --enable-wxpython +.endif</programlisting> + </example> + </sect2> + + <sect2 xml:id="wx-defined-variables"> + <title>Variáveis Definidas</title> + + <para>Estas variáveis estão disponíveis no port (depois de definir uma de <xref linkend="wx-ver-sel-table"/>).</para> + + <table frame="none" xml:id="wx-widgets-variables"> + <title>Variáveis definidas para ports que usam <application>wxWidgets</application></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>WX_CONFIG</varname></entry> + <entry>O caminho para o script <application>wxWidgets</application> <command>wx-config</command> (com nome diferente)</entry> + </row> + + <row> + <entry><varname>WXRC_CMD</varname></entry> + <entry>O caminho para o programa <application>wxWidgets</application> <command>wxrc</command> (com nome diferente)</entry> + </row> + + <row> + <entry><varname>WX_VERSION</varname></entry> + <entry>A versão do <application>wxWidgets</application> que será usada (por exemplo,<literal>2.6</literal>)</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2 xml:id="wx-premk"> + <title>Processando em <filename>bsd.port.pre.mk</filename></title> + + <para>Defina <varname>WX_PREMK</varname> para ser capaz de usar as variáveis logo após a inclusão do <filename>bsd.port.pre.mk</filename>.</para> + + <important> + <para>Ao definir <varname>WX_PREMK</varname>, a versão, dependências, componentes e variáveis definidas não serão alteradas mesmo se alterado as variáveis do port <application>wxWidgets</application> <emphasis>depois de</emphasis> incluir o <filename>bsd.port.pre.mk</filename>.</para> + </important> + + <example xml:id="wx-premk-example"> + <title>Usando Variáveis nos Comandos <application>wxWidgets</application></title> + + <para>Este fragmento ilustra o uso de <varname>WX_PREMK</varname> executando o script <command>wx-config</command> para obter a string de versão completa, atribuí-lo a uma variável e passá-lo para o programa.</para> + + <programlisting>USE_WX= 2.8 +WX_PREMK= yes + +.include <bsd.port.pre.mk> + +.if exists(${WX_CONFIG}) +VER_STR!= ${WX_CONFIG} --release + +PLIST_SUB+= VERSION="${VER_STR}" +.endif</programlisting> + </example> + + <note> + <para>As variaveis <application>wxWidgets</application> podem ser usadas com segurança em comandos quando estão dentro de targets sem a necessidade de <varname>WX_PREMK</varname>.</para> + </note> + </sect2> + + <sect2 xml:id="wx-additional-config-args"> + <title>Argumentos Adicionais do <command>configure</command></title> + + <para>Alguns scripts GNU <command>configure</command> não podem encontrar <application>wxWidgets</application> com apenas o conjunto de variáveis de ambiente <literal>WX_CONFIG</literal>, exigindo argumentos adicionais. <varname>WX_CONF_ARGS</varname> pode ser usado para fornecê-los.</para> + + <table frame="none" xml:id="wx-conf-args-values"> + <title>Valores Legais para <varname>WX_CONF_ARGS</varname></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Valor possível</entry> + <entry>Argumento resultante</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>absolute</literal></entry> + <entry><literal>--with-wx-config=${WX_CONFIG}</literal></entry> + </row> + + <row> + <entry><literal>relative</literal></entry> + <entry><literal>--with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}</literal></entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + </sect1> + + <sect1 xml:id="using-lua"> + <title>Usando <application>Lua</application></title> + + <para>Esta seção descreve o status das bibliotecas <application>Lua</application> na árvore de ports e sua integração com o sistema de ports.</para> + + <sect2 xml:id="lua-introduction"> + <title>Introdução</title> + + <para>Existem muitas versões das bibliotecas <application>Lua</application> e interpretadores correspondentes, que entram em conflito entre eles (instalam arquivos com o mesmo nome). Na árvore de ports este problema foi resolvido instalando cada versão sob um nome diferente usando sufixos de número de versão. </para> + + <para>A desvantagem óbvia disso é que cada aplicativo precisa ser modificado para encontrar a versão esperada. Mas isto pode ser resolvido adicionando alguns sinalizadores adicionais ao compilador e ao linker.</para> + </sect2> + + <sect2 xml:id="lua-version"> + <title>Seleção de Versão</title> + + <para>Um port usando <application>Lua</application> só precisa ter essa linha: </para> + + <programlisting>USES= lua</programlisting> + + <para>Se uma versão específica do Lua for necessária, as instruções sobre como selecioná-la são fornecidas no <link linkend="uses-lua"><literal>USES=lua</literal></link> parte do <xref linkend="uses"/>.</para> + </sect2> + + <sect2 xml:id="lua-defined-variables"> + <title>Variáveis Definidas</title> + + <para>Essas variáveis estão disponíveis no port.</para> + + <table frame="none" xml:id="using-lua-variables-ports"> + <title>Variáveis Definidas para Ports Que Usam <application>Lua</application></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Nome</entry> + <entry>Descrição</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>LUA_VER</varname></entry> + <entry>A versão <application>Lua</application> que será usada (por exemplo,<literal>5,1</literal>)</entry> + </row> + + <row> + <entry><varname>LUA_VER_STR</varname></entry> + <entry>A versão <application>Lua</application> sem os pontos (por exemplo,<literal>51</literal>) </entry> + </row> + + <row> + <entry><varname>LUA_PREFIX</varname></entry> + <entry>O prefixo onde o <application>Lua</application> (e os seus componentes) é instalado</entry> + </row> + + <row> + <entry><varname>LUA_SUBDIR</varname></entry> + <entry>O diretório sob <filename>${PREFIX}/bin</filename>, <filename>${PREFIX}/share</filename> e <filename>${PREFIX}/lib</filename> no qual o <application>Lua</application> é instalado</entry> + </row> + + <row> + <entry><varname>LUA_INCDIR</varname></entry> + <entry>O diretório no qual o <application>Lua</application> e os arquivos de cabeçalho <application>tolua</application> são instalados</entry> + </row> + + <row> + <entry><varname>LUA_LIBDIR</varname></entry> + <entry>O diretório no qual o <application>Lua</application> e as bibliotecas <application>tolua</application> são instalados</entry> + </row> + + <row> + <entry><varname>LUA_MODLIBDIR</varname></entry> + <entry>O diretório no qual as bibliotecas dos módulos <application>Lua</application> (<filename>.so</filename>) são instalados</entry> + </row> + + <row> + <entry><varname>LUA_MODSHAREDIR</varname></entry> + <entry>O diretório no qual os módulos <application>Lua</application> (<filename>.lua</filename>) são instalados</entry> + </row> + + <row> + <entry><varname>LUA_PKGNAMEPREFIX</varname></entry> + <entry>O prefixo do nome do pacote usado por módulos <application>Lua</application></entry> + </row> + + <row> + <entry><varname>LUA_CMD</varname></entry> + <entry>O caminho para o interpretador <application>Lua</application></entry> + </row> + + <row> + <entry><varname>LUAC_CMD</varname></entry> + <entry>O caminho para o compilador <application>Lua</application></entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + </sect1> + + <sect1 xml:id="using-iconv"> + <title>Usando <command>iconv</command></title> + + <para>Após 2013-10-08 (<revnumber>254273</revnumber>), o FreeBSD 10-CURRENT e as versões mais recentes têm um <command>iconv</command> nativo no sistema operacional. Em versões anteriores, o <package role="port">converters/libiconv</package> era usado como dependência.</para> + + <para>Para softwares que precisam do <command>iconv</command>, defina <literal>USES=iconv</literal>. As versões do FreeBSD antes do 10-CURRENT em 2013-08-13 (<revnumber>254273</revnumber>) não tem um <command>iconv</command> nativo. Nestas versões anteriores, uma dependência do <package role="port">converters/libiconv</package> será adicionada automaticamente. </para> + + <para>Quando um port define <literal>USES=iconv</literal>, estas variáveis estarão disponíveis:</para> + + <informaltable frame="none" pgwide="0"> + <tgroup cols="4"> + <thead> + <row> + <entry>Nome da variável</entry> + <entry>Propósito</entry> + <entry>Valor antes do FreeBSD 10-CURRENT <revnumber>254273</revnumber>(2013-08-13)</entry> + <entry>Valor após o FreeBSD 10-CURRENT <revnumber>254273</revnumber>(2013-08-13)</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>ICONV_CMD</varname></entry> + <entry>Diretório onde o binário <command>iconv</command> reside</entry> + <entry><literal>${LOCALBASE}/bin/iconv</literal></entry> + <entry><filename>/usr/bin/iconv</filename></entry> + </row> + + <row> + <entry><varname>ICONV_LIB</varname></entry> + <entry>argumento do <command>ld</command> para vincular ao <filename>libiconv</filename> (se necessário)</entry> + <entry><literal>-liconv</literal></entry> + <entry>(vazio)</entry> + </row> + + <row> + <entry><varname>ICONV_PREFIX</varname></entry> + <entry>Diretório onde a implementação do <command>iconv</command> reside (útil para configurar scripts)</entry> + <entry><literal>${LOCALBASE}</literal></entry> + <entry><filename>/usr</filename></entry> + </row> + + <row> + <entry><varname>ICONV_CONFIGURE_ARG</varname></entry> + <entry>Argumento de configuração pré-configurado para scripts de configuração.</entry> + <entry><literal>--with-libiconv-prefix=${LOCALBASE}</literal></entry> + <entry>(vazio)</entry> + </row> + + <row> + <entry><varname>ICONV_CONFIGURE_BASE</varname></entry> + <entry>Argumento de configuração pré-configurado para scripts de configuração.</entry> + <entry><literal>--with-libiconv=${LOCALBASE}</literal></entry> + <entry>(vazio)</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Esses dois exemplos preenchem automaticamente as variáveis com o valor correto para sistemas usando respectivamente o <package role="port">converters/libiconv</package> ou o <command>iconv</command> nativo:</para> + + <example xml:id="iconv-simple-use"> + <title>Simples uso do <command>iconv</command></title> + + <programlisting>USES= iconv +LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB}</programlisting> + </example> + + <example xml:id="iconv-configure-use"> + <title>Uso do <command>iconv</command> com <command>configure</command></title> + + <programlisting>USES= iconv +CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}</programlisting> + </example> + + <para>Como mostrado acima, a variável <varname>ICONV_LIB</varname> estará vazia quando um <command>iconv</command> nativo estiver presente. Isso pode ser usado para detectar o <command>iconv</command> nativo e responder adequadamente.</para> + + <para>Às vezes um programa tem um argumento <command>ld</command> ou caminho de pesquisa codificado em um <filename>Makefile</filename> ou no script configure. Essa abordagem pode ser usada para resolver esse problema:</para> + + <example xml:id="iconv-reinplace"> + <title>Corrigindo Hardcoded <literal>-liconv</literal></title> + + <programlisting>USES= iconv + +post-patch: + @${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/Makefile</programlisting> + </example> + + <para>Em alguns casos, é necessário definir valores alternativos ou executar operações dependendo se há um <command>iconv</command> nativo. O <filename>bsd.port.pre.mk</filename> deve ser incluído antes de testar o valor de <varname>ICONV_LIB</varname>:</para> + + <example xml:id="iconv-conditional"> + <title>Verificando Disponibilidade do <command>iconv</command> Nativo</title> + + <programlisting>USES= iconv + +.include <bsd.port.pre.mk> + +post-patch: +.if empty(ICONV_LIB) + # native iconv detected + @${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh +.endif + +.include <bsd.port.post.mk></programlisting> + </example> + </sect1> + + <sect1 xml:id="using-xfce"> + <title>Usando o Xfce</title> + + <para>Ports que precisam de bibliotecas ou aplicações <application>Xfce</application>, utilizam <literal>USES=xfce</literal>.</para> + + <para>Dependencias específicas de bibliotecas e aplicativos <application>Xfce</application> são definidas com valores atribuídos a <varname>USE_XFCE</varname>. Eles são definidos em <filename>/usr/ports/Mk/Uses/xfce.mk</filename>. Os valores possíveis são:</para> + + <variablelist> + <title>Valores de <varname>USE_XFCE</varname></title> + + <varlistentry> + <term>garcon</term> + + <listitem> + <para><package role="port">sysutils/garcon</package></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>libexo</term> + + <listitem> + <para><package role="port">x11/libexo</package></para> + </listitem> + </varlistentry> + + <varlistentry> + + <term>libgui</term> + + <listitem> + <para><package role="port">x11-toolkits/libxfce4gui</package></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>libmenu</term> + + <listitem> + <para><package role="port">x11/libxfce4menu</package></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>libutil</term> + + <listitem> + <para><package role="port">x11/libxfce4util</package></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>painel</term> + + <listitem> + <para><package role="port">x11-wm/xfce4-panel</package></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>thunar</term> + + <listitem> + <para><package role="port">x11-fm/thunar</package></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>xfconf</term> + + <listitem> + <para><package role="port">x11/xfce4-conf</package></para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="use-xfce"> + <title>Exemplo de <varname>USES=xfce</varname></title> + + <programlisting>USES= xfce +USE_XFCE= libmenu</programlisting> + </example> + + <example xml:id="use-xfce-gtk3"> + <title>Usando os Próprios Widgets GTK3 do Xfce</title> + + <para>Neste exemplo, o aplicativo portado usa os widgets específicos do <application>GTK3</application>, o <package role="port">x11/libxfce4menu</package> e o <package role="port">x11/xfce4-conf</package>.</para> + + <programlisting>USES= xfce:gtk3 +USE_XFCE= libmenu xfconf</programlisting> + </example> + + <tip> + <para>Os componentes <application>Xfce</application> incluídos dessa maneira incluirão automaticamente todas as dependências necessárias. Não é mais necessário especificar a lista inteira. Se o port precisar apenas de <package role="port">x11-wm/xfce4-panel</package>, use:</para> + + <programlisting>USES= xfce +USE_XFCE= panel</programlisting> + + <para>Não há necessidade de listar os componentes que o <package role="port">x11-wm/xfce4-panel</package> precisa para ele mesmo, desta forma:</para> + + <programlisting>USES= xfce +USE_XFCE= libexo libmenu libutil panel</programlisting> + + <para>Contudo, os componentes <application>Xfce</application> e as dependências do port que não dependem do <application>Xfce</application> devem ser incluídas explicitamente. Não conte com um componente <application>Xfce</application> para fornecer uma sub-dependência diferente de si para o port principal. </para> + </tip> + </sect1> + + <sect1 xml:id="using-databases"> + <title>Usando Bancos de Dados</title> + + <para>Utilize uma das macros <varname>USES</varname> de <xref linkend="using-databases-uses"/> para adicionar a dependência de um banco de dados.</para> + + <table frame="none" xml:id="using-databases-uses"> + <title>Banco de Dados de Macros <varname>USES</varname></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Base de Dados</entry> + <entry>Macro <varname>USES</varname></entry> + </row> + </thead> + + <tbody> + <row> + <entry>Berkeley DB</entry> + <entry><link linkend="uses-bdb"><literal>bdb</literal></link></entry> + </row> + + <row> + <entry>MariaDB, MySQL, Percona</entry> + <entry><link linkend="uses-mysql"><literal>mysql</literal></link></entry> + </row> + + <row> + <entry>PostgreSQL</entry> + <entry><link linkend="uses-pgsql"><literal>pgsql</literal></link></entry> + </row> + + <row> + <entry>SQLite</entry> + <entry><link linkend="uses-sqlite"><literal>sqlite</literal></link></entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="using-databases-bdb-ex1"> + <title>Usando o Berkeley DB 6</title> + + <programlisting>USES= bdb:6</programlisting> + + <para>Veja <xref linkend="uses-bdb"/> para maiores informações.</para> + </example> + + <example xml:id="using-databases-mysql-ex1"> + <title>Usando MySQL</title> + + <para>Quando um port precisa da biblioteca cliente do <application>MySQL</application>, adicione</para> + + <programlisting>USES= mysql</programlisting> + + <para>Veja <xref linkend="uses-mysql"/> para mais informações.</para> + </example> + + <example xml:id="using-databases-pgsql-ex1"> + <title>Usando PostgreSQL</title> + + <para>Quando um port precisar do servidor <application>PostgreSQL</application> versão 9.6 ou posterior, adicione</para> + + <programlisting>USES= pgsql:9.6+ +WANT_PGSQL= server</programlisting> + + <para>Veja <xref linkend="uses-pgsql"/> para mais informações.</para> + </example> + + <example xml:id="using-databases-sqlite-ex1"> + <title>Usando SQLite 3</title> + + <programlisting>USES= sqlite:3</programlisting> + + <para>Veja <xref linkend="uses-sqlite"/> para mais informações.</para> + </example> + </sect1> + + <sect1 xml:id="rc-scripts"> + <title>Iniciando e Parando Serviços (com scripts <literal>rc</literal>)</title> + + <para>Os scripts <filename>rc.d</filename> são usados para iniciar serviços na inicialização do sistema e para fornecer aos administradores uma maneira padrão de parar, iniciar e reiniciar o serviço. Ports se integram ao sistema de estrutura do <filename>rc.d</filename>. Detalhes sobre seu uso podem ser encontrados no <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/configtuning-rcd.html">capitulo sobre rc.d</link> do handbook. A explicação detalhada dos comandos disponíveis é fornecida em <citerefentry><refentrytitle>rc</refentrytitle><manvolnum>8</manvolnum></citerefentry> e <citerefentry><refentrytitle>rc.sub</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Finalmente, existe um <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/rc-scripting">artigo</link> sobre aspectos práticos do sistema de scripts do <filename>rc.d</filename>.</para> + + <para>Com um port mítico chamado<replaceable>doorman</replaceable>, o qual precisa iniciar um daemon <replaceable>doormand</replaceable>. Adicione o seguinte ao <filename>Makefile</filename>:</para> + + <programlisting>USE_RC_SUBR= <replaceable>doormand</replaceable></programlisting> + + <para>Vários scripts podem ser listados e serão instalados. Os scripts devem ser colocados no subdiretório <filename>files</filename> e um sufixo <literal>.in</literal> deve ser adicionado ao nome do arquivo. Expansões padrões <varname>SUB_LIST</varname> serão executadas neste arquivo. Usar as expansões <literal>%%PREFIX%%</literal> e <literal>%%LOCALBASE%%</literal> também é fortemente encorajado. Veja mais sobre a <varname>SUB_LIST</varname> na <link linkend="using-sub-files">seção relevante</link>.</para> + + <para>A partir do FreeBSD 6.1-RELEASE, scripts locais <filename>rc.d</filename> (incluindo aqueles instalados pelos ports) estão incluídos no <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> do sistema base.</para> + + <para>Um exemplo simples de script <filename>rc.d</filename> para iniciar o daemon doormand:</para> + + <programlisting>#!/bin/sh + +# $FreeBSD$ +# +# PROVIDE: <replaceable>doormand</replaceable> +# REQUIRE: LOGIN +# KEYWORD: shutdown +# +# Add these lines to /etc/rc.conf.local or /etc/rc.conf +# to enable this service: +# +# <replaceable>doormand</replaceable>_enable (bool): Set to NO by default. +# Set it to YES to enable <replaceable>doormand</replaceable>. +# <replaceable>doormand</replaceable>_config (path): Set to %%PREFIX%%/etc/<replaceable>doormand/doormand.cf</replaceable> +# by default. + +. /etc/rc.subr + +name=<replaceable>doormand</replaceable> +rcvar=<replaceable>doormand</replaceable>_enable + +load_rc_config $name + +: ${<replaceable>doormand</replaceable>_enable:="NO"} +: ${<replaceable>doormand</replaceable>_config="%%PREFIX%%/etc/<replaceable>doormand/doormand.cf</replaceable>"} + +command=%%PREFIX%%/sbin/${name} +pidfile=/var/run/${name}.pid + +command_args="<replaceable>-p $pidfile -f $doormand_config</replaceable>" + +run_rc_command "$1"</programlisting> + + <para>A menos que haja uma boa razão para iniciar o serviço mais cedo, ou ele seja executado como um usuário específico (diferente de root), todos os scripts de ports devem usar:</para> + + <programlisting>REQUIRE: LOGIN</programlisting> + + <para>Se o script de inicialização iniciar um daemon que deve ser desligado, o seguinte acionará uma parada do serviço no desligamento do sistema:</para> + + <programlisting>KEYWORD: shutdown</programlisting> + + <para>Se o script não está iniciando um serviço persistente, isso não é necessário.</para> + + <para>Para os elementos de configuração opcional o estilo "=" de atribuição de variável padrão é preferível ao estilo ":=", já que o primeiro define um valor padrão apenas se a variável não estiver definida, e o segundo define um se a variável não está definida <emphasis>ou</emphasis> se ela é nula. Um usuário pode muito bem incluir algo como:</para> + + <programlisting><replaceable>doormand</replaceable>_flags=""</programlisting> + + <para>no seu <filename>rc.conf.local</filename>, e uma substituição de variável usando ":=" substituirá inadequadamente a intenção do usuário. A variável <literal>_enable</literal> não é opcional e deve usar o ":" por padrão.</para> + + <important> + <para>Os Ports <emphasis>não devem</emphasis> iniciar e parar seus serviços durante a instalação e desinstalação. Não abuse das keywords <filename>plist</filename> descritas em <xref linkend="plist-keywords-base-exec"/> executando comandos que modificam o sistema em execução, incluindo iniciar ou interromper serviços.</para> + </important> + + <sect2 xml:id="rc-scripts-checklist"> + <title>Pre-Commit Checklist</title> + + <para>Antes de contribuir um port com um script <filename>rc.d</filename>, e mais importante, antes de realizar o commit de um, por favor consulte esta lista de verificação para ter certeza de que ele está pronto.</para> + + <para>O port <package role="port">devel/rclint</package> pode verificar a maioria destes itens, mas não substitui uma revisão adequada.</para> + + <procedure> + <step> + <para>Se este é um novo arquivo, ele tem uma extensão <filename>.sh</filename>? Se assim for, isso deve ser mudado para apenas <filename><replaceable>file</replaceable>.in</filename> uma vez que os arquivos <filename>rc.d</filename> não podem terminar com essa extensão.</para> + </step> + + <step> + <para>O arquivo tem uma tag <literal>$FreeBSD$</literal>?</para> + </step> + + <step> + <para>O nome do arquivo (menos <filename>.in</filename>), a linha <literal>PROVIDE</literal> e <literal>$</literal><replaceable>name</replaceable> são as mesmas? O nome do arquivo ao corresponder com o <literal>PROVIDE</literal> irá facilitar a depuração, especialmente para problemas de <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Combinar o nome do arquivo e o <literal>$</literal><replaceable>name</replaceable> torna mais fácil descobrir quais variáveis são relevantes no <filename>rc.conf[.local]</filename>. Isso também é uma política para todos os novos scripts, incluindo aqueles no sistema base.</para> + </step> + + <step> + <para>A linha <literal>REQUIRE</literal> está definida para <literal>LOGIN</literal>? Isso é obrigatório para scripts que são executados como um usuário não root. Se ele for executado como root, há uma boa razão para ele ser executado antes de <literal>LOGIN</literal>? Caso contrário, ele deve ser executado depois para que os scripts locais possam ser agrupados em um ponto no <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> depois que quase tudo no sistema base já estiver rodando.</para> + </step> + + <step> + <para>O script inicia um serviço persistente? Em caso afirmativo, ele deve ter o <literal>KEYWORD: shutdown</literal>.</para> + </step> + + <step> + <para>Certifique-se de que não há um <literal>KEYWORD: FreeBSD</literal> presente. Isto não foi necessário nem desejável durante anos. Isto também é uma indicação de que o novo script foi copiado/colado de um script antigo, portanto, um cuidado extra deve ser dado à revisão.</para> + </step> + + <step> + <para>Se o script usa uma linguagem interpretada como o <command>perl</command>, o <command>python</command> ou o <command>ruby</command>, certifique-se de que o <varname>command_interpreter</varname> está definido adequadamente, por exemplo, para o <application>Perl</application>, adicione <literal>PERL=${PERL}</literal> para a <varname>SUB_LIST</varname> e utilize <literal>%%PERL%%</literal>. De outra forma,</para> + + <screen><prompt>#</prompt> <userinput>service <replaceable>name</replaceable> stop</userinput></screen> + + <para>provavelmente não funcionará corretamente. Consulte <citerefentry><refentrytitle>service</refentrytitle><manvolnum>8</manvolnum></citerefentry> para maiores informações.</para> + </step> + + <step> + <para>Todas as ocorrências de <filename>/usr/local</filename> foram substituídas por <literal>%%PREFIX%%</literal>?</para> + </step> + + <step> + <para>As atribuições das variáveis padrão vêm depois de <function>load_rc_config</function>?</para> + </step> + + <step> + <para>Existem atribuições padrões para sequências vazias? Elas devem ser removidas, mas verifique se a opção está documentada nos comentários na parte superior do arquivo.</para> + </step> + + <step> + <para>As variáveis definidas estão realmente sendo utilizadas no script?</para> + </step> + + <step> + <para>As opções listadas no padrão <replaceable>name</replaceable><varname>_flags</varname> são realmente obrigatórias? Se assim for, elas devem estar em <varname>command_args</varname>. A opção <option>-d</option> é uma flag vermelha (com o perdão do trocadilho) aqui, já que geralmente é a opção de "daemonizar" o processo e, portanto, é realmente obrigatório.</para> + </step> + + <step> + <para>O <varname><replaceable>name</replaceable>_flags</varname> nunca deve ser incluído em <varname>command_args</varname> (e vice-versa, embora esse erro seja menos comum).</para> + </step> + + <step> + <para>O script executa qualquer código incondicionalmente? Isso é desaprovado. Normalmente, essas coisas devem ser tratadas através de um <function>start_precmd</function>.</para> + </step> + + <step> + <para>Todos os testes booleanos devem usar a função <function>checkyesno</function>. Nenhum teste deve usar <literal>[Yy][Ee][Ss]</literal>, etc.</para> + </step> + + <step> + <para>Se houver um loop (por exemplo, esperando que algo inicie), ele tem um contador para terminar o loop? Não queremos que a inicialização seja bloqueada para sempre se houver um erro.</para> + </step> + + <step> + <para>O script cria arquivos ou diretórios que precisam de permissões específicas, por exemplo, um <filename>pid</filename> que precisa ser de propriedade do usuário que executa o processo? Em vez da rotina tradicional <citerefentry><refentrytitle>touch</refentrytitle><manvolnum>1</manvolnum></citerefentry>/<citerefentry><refentrytitle>chown</refentrytitle><manvolnum>8</manvolnum></citerefentry>/<citerefentry><refentrytitle>chmod</refentrytitle><manvolnum>1</manvolnum></citerefentry>, considere usar <citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> com os argumentos de linha de comando apropriados para fazer todo o procedimento com um passo.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="users-and-groups"> + <title>Adicionando Usuários e Grupos</title> + + <para>Alguns ports exigem que uma conta de usuário específica esteja presente, geralmente para daemons executados como esse usuário. Para esses ports, escolha um UID <emphasis>único</emphasis> entre 50 a 999 e registre-o em <filename>ports/UIDs</filename> (para usuários) e em <filename>ports/GIDs</filename>(para grupos). A identificação única deve ser a mesma para usuários e grupos.</para> + + <para>Por favor, inclua um patch para estes dois arquivos quando for necessário que um novo usuário ou grupo seja criado para o port.</para> + + <para>Então use <varname>USERS</varname> e <varname>GROUPS</varname> + dentro do <filename>Makefile</filename> e o usuário será criado automaticamente ao instalar o port.</para> + + <programlisting>USERS= pulse +GROUPS= pulse pulse-access pulse-rt</programlisting> + + <para>A lista atual de UIDs e GIDs reservados pode ser encontrada em <filename>ports/UIDs</filename> e <filename>ports/GIDs</filename>.</para> + </sect1> + + <sect1 xml:id="requiring-kernel-sources"> + <title>Ports que Dependem dos Fontes do kernel</title> + + <para>Alguns ports (como módulos carregáveis do kernel) precisam dos arquivos fonte do kernel para que o port possa ser compilado. Aqui está a maneira correta de determinar se o usuário os instalou:</para> + + <programlisting>USES= kmod</programlisting> + + <para>Além desta verificação, o recurso <literal>kmod</literal> cuida da maioria dos itens que esses ports precisam levar em consideração.</para> + </sect1> + + <sect1 xml:id="go-libs"> + <title>Bibliotecas Go</title> + + <para>Os ports não devem empacotar ou instalar bibliotecas Go ou código-fonte. Apenas <filename>lang/go*</filename> deve instalar em <varname>GO_SRCDIR</varname> e <varname>GO_LIBDIR</varname>. Os ports Go devem buscar as dependências na hora da compilação e devem instalar apenas programas que os usuários precisam, não o que os desenvolvedores Go precisam.</para> + + <para>Ports devem (por ordem de preferência):</para> + + <itemizedlist> + <listitem> + <para>Usar as dependências fornecidas no código fonte do pacote.</para> + </listitem> + + <listitem> + <para>Buscar as versões das dependências especificadas pelo upstream (no caso do vendor.json ou similar).</para> + </listitem> + + <listitem> + <para>Como um último recurso (as dependências não estão incluídas e nem as versões foram especificadas exatamente) busque as versões das dependências disponíveis no momento do desenvolvimento/release.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="shell-completion"> + <title>Arquivos Shell Completion</title> + + <para>Muitos shells modernos (incluindo bash, tcsh e zsh) suportam parâmetro e/ou opção de tab-completion. Esse suporte geralmente vem de arquivos completion, os quais contêm as definições de como as tabs completion funcionarão para um determinado comando. As vezes ports vem com seus arquivos completion, ou os mantenedores de ports podem ter criado um eles mesmos.</para> + + <para>Quando disponível, os arquivos de completion devem sempre ser instalados. Não é necessário fazer uma opção para eles. Apesar que se uma opção for usada, sempre habilite-a em <varname>OPTIONS_DEFAULT</varname>.</para> + + <table frame="none" xml:id="shell-completion-paths"> + <title>Caminhos dos arquivos shell completion</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><command>bash</command></entry> + <entry><filename>${PREFIX}/etc/bash_completion.d</filename></entry> + </row> + + <row> + <entry><command>zsh</command></entry> + <entry><filename>${PREFIX}/share/zsh/site-functions</filename></entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Não registre nenhuma dependência nos próprios shells.</para> + </sect1> +</chapter> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ + +--> + +<chapter version="5.0" xml:id="flavors"> + + <title>Flavors</title> + + <sect1 xml:id="flavors-intro"> + <title>Uma Introdução aos Flavors</title> + + <para>Os flavors são uma maneira de ter várias variações de um port. O port é construído várias vezes, com variações.</para> + + <para>Por exemplo, um port pode ter uma versão normal com muitos recursos e algumas dependências, e uma versão leve <quote>lite</quote> com apenas recursos básicos e dependências mínimas.</para> + + <para>Outro exemplo poderia ser, um port pode ter um flavor <application>GTK</application> e um <application>QT</application>, dependendo de qual kit de ferramentas ele usa.</para> </sect1> + + <sect1 xml:id="flavors-using"> + <title>Usando FLAVORS</title> + + <para>Para declarar um port com vários flavors, adicione <varname>FLAVORS</varname> no seu <filename>Makefile</filename>. O primeiro flavor em <varname>FLAVORS</varname> é o flavor padrão.</para> + + <tip> + <para>Isso pode ajudar a simplificar a lógica do <filename>Makefile</filename> para também definir um <varname>FLAVOR</varname> como:</para> + + <programlisting>FLAVOR?= ${FLAVORS:[1]}</programlisting> + </tip> + + <important> + <para>Para distinguir os flavors das opções, que são sempre letras maiúsculas, os nomes dos flavors podem conter <emphasis>apenas</emphasis> letras minúsculas, números e underline <literal>_</literal>.</para> + </important> + + <example xml:id="flavors-using-ex1"> + <title>Uso Básico de Flavors</title> + + <para>Se um port tiver um port slave <quote>lite</quote>, o port slave pode ser removido, e o port pode ser convertido em flavors com:</para> + + <programlisting>FLAVORS= default lite +lite_PKGNAMESUFFIX= -lite +[...] +.if ${FLAVOR:U} != lite +[enable non lite features] +.endif</programlisting> + + <note> + <para>O primeiro flavor é o padrão, e é chamado aqui de <literal>default</literal>. Não é uma obrigação e, se possível, use um nome de flavor mais específico, como em <xref linkend="flavors-using-ex2"/>.</para> + </note> + </example> + + <example xml:id="flavors-using-ex2"> + <title>Outro Uso Básico de Flavors</title> + + <para>Se um port tiver um port slave <literal>-nox11</literal>, o port slave pode ser removido, e o port pode ser convertido em flavors com:</para> + + <programlisting>FLAVORS= x11 nox11 +FLAVOR?= ${FLAVORS:[1]} +nox11_PKGNAMESUFFIX= -nox11 +[...] +.if ${FLAVOR} == x11 +[enable x11 features] +.endif</programlisting> + </example> + + <example xml:id="flavors-using-ex3"> + <title>Uso Mais Complexo de Flavors</title> + + <para>Aqui está um excerto ligeiramente editado do que está presente em <package role="port">devel/libpeas</package>, um port que usa os <link linkend="flavors-auto-python">flavors <application>Python</application></link>. Com as versões padrões do <application>Python</application> 2 e 3 sendo 2.7 e 3.6, ele irá automaticamente mudar para <literal>FLAVORS=py27 py36</literal></para> + + <programlisting>USES= gnome python +USE_PYTHON= flavors <co xml:id="flavors-using-ex2-use"/> + +.if ${FLAVOR:Upy27:Mpy2*} <co xml:id="flavors-using-ex2-if"/> +USE_GNOME= pygobject3 <co xml:id="flavors-using-ex2-pygobject3"/> + +CONFIGURE_ARGS+= --enable-python2 --disable-python3 + +BUILD_WRKSRC= ${WRKSRC}/loaders/python <co xml:id="flavors-using-ex2-build2"/> +INSTALL_WRKSRC= ${WRKSRC}/loaders/python <co xml:id="flavors-using-ex2-install2"/> +.else # py3* +USE_GNOME+= py3gobject3 <co xml:id="flavors-using-ex2-py3gobject3"/> + +CONFIGURE_ARGS+= --disable-python2 --enable-python3 \ + ac_cv_path_PYTHON3_CONFIG=${LOCALBASE}/bin/python${PYTHON_VER}-config <co xml:id="flavors-using-ex2-ac_cv"/> + +BUILD_WRKSRC= ${WRKSRC}/loaders/python3 <co xml:id="flavors-using-ex2-build3"/> +INSTALL_WRKSRC= ${WRKSRC}/loaders/python3 <co xml:id="flavors-using-ex2-install3"/> +.endif + +py34_PLIST= ${.CURDIR}/pkg-plist-py3 <co xml:id="flavors-using-ex2-plist34"/> +py35_PLIST= ${.CURDIR}/pkg-plist-py3 <co xml:id="flavors-using-ex2-plist35"/> +py36_PLIST= ${.CURDIR}/pkg-plist-py3 <co xml:id="flavors-using-ex2-plist36"/></programlisting> + + <calloutlist> + <callout arearefs="flavors-using-ex2-use"> + <para>Este port não usa o <literal>USE_PYTHON=distutils</literal> mas precisa do flavor <application>Python</application> de qualquer maneira.</para> + </callout> + + <callout arearefs="flavors-using-ex2-if"> + <para>Para proteger contra o <varname>FLAVOR</varname> estar vazio, o que causaria um erro no <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>, use <literal>${FLAVOR:U}</literal> em comparações de strings em vez de <literal>${FLAVOR}</literal>.</para> + </callout> + + <callout arearefs="flavors-using-ex2-pygobject3 flavors-using-ex2-py3gobject3"> + <para>As ligações gobject3 do<application>Gnome</application> <application>Python</application> têm dois nomes diferentes, um para <application>Python</application>2, pygobject3 e um para <application>Python</application>3, py3gobject3.</para> + </callout> + + <callout arearefs="flavors-using-ex2-build2 flavors-using-ex2-install2 flavors-using-ex2-build3 flavors-using-ex2-install3"> + <para>O script <command>configure</command> tem que ser executado em <filename>${WRKSRC}</filename>, mas estamos interessados apenas em compilar e instalar as partes Python 2 ou Python 3 do software, então configure os diretórios base de compilação e instalação apropriadamente.</para> + </callout> + + <callout arearefs="flavors-using-ex2-ac_cv"> + <para>Sugestão sobre o nome correto do caminho do script de configuração do <application>Python</application> 3.</para> + </callout> + + <callout arearefs="flavors-using-ex2-plist34 flavors-using-ex2-plist35 flavors-using-ex2-plist36"> + <para>A lista de empacotamento é diferente quando compilada com <application>Python</application> 3. Como existem três possíveis versões do <application>Python</application>3 , defina <varname>PLIST</varname> para todos os três usando o <link linkend="flavors-using-helpers">helper</link>.</para> + </callout> + </calloutlist> + </example> + + <sect2 xml:id="flavors-using-helpers"> + <title>Flavors Helpers</title> + + <para>Para tornar o <filename>Makefile</filename> mais fácil de ser escrito, existem alguns flavors helpers.</para> + + <para>Esta lista de helpers definirá sua variável:</para> + + <itemizedlist> + <listitem> + <para><varname><replaceable>flavor</replaceable>_PKGNAMEPREFIX</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_PKGNAMESUFFIX</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_PLIST</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_DESCR</varname></para> + </listitem> + </itemizedlist> + + <para>Esta lista de helpers será anexada à sua variável:</para> + + <itemizedlist> + <listitem> + <para><varname><replaceable>flavor</replaceable>_CONFLICTS</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_CONFLICTS_BUILD</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_CONFLICTS_INSTALL</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_PKG_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_EXTRACT_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_PATCH_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_FETCH_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_BUILD_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_LIB_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_RUN_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname><replaceable>flavor</replaceable>_TEST_DEPENDS</varname></para> + </listitem> + </itemizedlist> + + <example xml:id="flavors-helpers-ex1"> + <title>Flavor Específico <varname>PKGNAME</varname>.</title> + + <para>Como todos os pacotes devem ter um nome de pacote diferente, os flavors devem mudar os seus, usando <varname><replaceable>flavor</replaceable>_PKGNAMEPREFIX</varname> e o <varname><replaceable>flavor</replaceable>_PKGNAMESUFFIX</varname> torna isso fácil:</para> + + <programlisting>FLAVORS= normal lite +lite_PKGNAMESUFFIX= -lite</programlisting> + </example> + </sect2> + </sect1> + + <sect1 xml:id="flavors-auto-php"> + <title><literal>USES=php</literal> e Flavors</title> + + <para>Ao usar o <link linkend="uses-php">USES=php</link> com um destes argumentos, <literal>phpize</literal>, <literal>ext</literal>, <literal>zend</literal> ou <literal>pecl</literal>, o port terá automaticamente o <varname>FLAVORS</varname> preenchido com a versão <application>PHP</application> que ele suporta.</para> + + <note> + <para>Todos os exemplos assumem que as versões PHP suportadas atualmente são 5.6, 7.0, 7.1 e 7.2.</para> + </note> + + <example xml:id="flavors-auto-php-ex1"> + <title>Extensão Simples <literal>USES=php</literal></title> + + <para>Isso irá gerar o pacote para todas as versões suportadas:</para> + + <programlisting>PORTNAME= some-ext +PORTVERSION= 0.0.1 +PKGNAMEPREFIX= ${PHP_PKGNAMEPREFIX} + +USES= php:ext</programlisting> + + <para>Isto irá gerar pacotes para todas as versões suportadas, menos a 7.2:</para> + + <programlisting>PORTNAME= some-ext +PORTVERSION= 0.0.1 +PKGNAMEPREFIX= ${PHP_PKGNAMEPREFIX} + +USES= php:ext +IGNORE_WITH_PHP= 72</programlisting> + </example> + + <sect2 xml:id="flavors-auto-php-app"> + <title>Flavors PHP com Aplicações PHP</title> + + <para>Aplicações PHP também podem ter flavors.</para> + + <para>Isso permite gerar pacotes para todas as versões do PHP, para que os usuários possam usá-los com qualquer versão que precisarem em seus servidores.</para> + + <important> + <para>Aplicações PHP que são acrescidas de flavors <emphasis>devem</emphasis> acrescentar <varname>PHP_PKGNAMESUFFIX</varname> aos nomes dos pacotes.</para> + </important> + + <example xml:id="flavors-auto-php-app-ex1"> + <title>Adicionando Flavors em uma Aplicação PHP</title> + + <para>Incluir o suporte de Flavors em uma aplicação PHP é simples:</para> + + <programlisting>PKGNAMESUFFIX= ${PHP_PKGNAMESUFFIX} + +USES= php:flavors</programlisting> + </example> + + <tip> + <para>Ao adicionar uma dependência em um port com flavors <application>PHP</application>, use <literal>@${PHP_FLAVOR}</literal>. <emphasis>Nunca</emphasis> use <varname>FLAVOR</varname> diretamente.</para> + </tip> + </sect2> + </sect1> + + <sect1 xml:id="flavors-auto-python"> + <title><literal>USES=python</literal> e Flavors</title> + + <para>Ao usar <link linkend="uses-python"><literal>USES=python</literal></link> e <literal>USE_PYTHON=distutils</literal>, o port irá automaticamente preencher <varname>FLAVORS</varname> com a versão <application>Python</application> que suporta.</para> + + <example xml:id="flavors-auto-python-ex1"> + <title>Simples <literal>USES=python</literal></title> + + <para>Supondo que as versões suportadas do <application>Python</application> são 2.7, 3.4, 3.5 e 3.6, e a versão padrão do <application>Python</application> 2 e 3 são 2.7 e 3.6, um port com:</para> + + <programlisting>USES= python +USE_PYTHON= distutils</programlisting> + + <para>Receberá esses flavors: <literal>py27</literal> e <literal>py36</literal>.</para> + + <programlisting>USES= python +USE_PYTHON= distutils allflavors</programlisting> + + <para>Receberá esses flavors: <literal>py27</literal>, <literal>py34</literal>, <literal>py35</literal> e <literal>py36</literal>.</para> + </example> + + <example xml:id="flavors-auto-python-ex2"> + <title><literal>USES=python</literal> com Requisitos de Versão</title> + + <para>Supondo que as versões suportadas do <application>Python</application> são 2.7, 3.4, 3.5 e 3.6, e a versão padrão do <application>Python</application> 2 e 3 são 2.7 e 3.6, um port com:</para> + + <programlisting>USES= python:-3.5 +USE_PYTHON= distutils</programlisting> + + <para>Vai ter esse flavor: <literal>py27</literal>.</para> + + <programlisting>USES= python:-3.5 +USE_PYTHON= distutils allflavors</programlisting> + + <para>Receberá esses flavors: <literal>py27</literal>, <literal>py34</literal> e <literal>py35</literal>.</para> + + <programlisting>USES= python:3.4+ +USE_PYTHON= distutils</programlisting> + + <para>Vai ter esse flavor: <literal>py36</literal>.</para> + + <programlisting>USES= python:3.4+ +USE_PYTHON= distutils allflavors</programlisting> + + <para>Receberá esses flavors: <literal>py34</literal>, <literal>py35</literal> e <literal>py36</literal>.</para> + </example> + + <para>A variável <varname>PY_FLAVOR</varname> é disponibilizada para depender da versão correta dos módulos <application>Python</application>. Todas as dependências em ports Python com flavors devem usar <varname>PY_FLAVOR</varname>, e não <varname>FLAVOR</varname> diretamente.</para> + + <example xml:id="flavors-auto-python-ex3"> + <title>Para um port que não usa <literal>distutils</literal></title> + + <para>Se a versão padrão do <application>Python</application>3 é 3.6, o seguinte irá definir a variável <varname>PY_FLAVOR</varname> para <literal>py36</literal>:</para> + + <programlisting>RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}mutagen>0:audio/py-mutagen@${PY_FLAVOR} + +USES= python:3.5+</programlisting> + </example> + </sect1> +</chapter> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter version="5.0" xml:id="plist"> + + <title>Práticas Avançadas de <filename>pkg-plist</filename></title> + + <sect1 xml:id="plist-sub"> + <title>Alterando o <filename>pkg-plist</filename> Baseado em Variáveis Make</title> + + <para>Alguns ports, particularmente os <literal>p5-</literal> ports, precisam mudar seus <filename>pkg-plist</filename> dependendo de quais opções eles são configurados com (ou versão de <literal>perl</literal>, no caso de <literal>p5-</literal> ports). Para tornar isso fácil, todas as instâncias <filename>pkg-plist</filename> de <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal> e <literal>%%PERL_VERSION%%</literal> serão substituídas apropriadamente. O valor de <literal>%%OSREL%%</literal> é a revisão numérica do sistema operacional (por exemplo,<literal>4.9</literal>). <literal>%%PERL_VERSION%%</literal> e <literal>%%PERL_VER%%</literal> é o número completo da versão <command>perl</command> (por exemplo,<literal>5.8.9</literal>). Muitos outros <literal>%%<replaceable>VARS</replaceable>%%</literal> relacionados aos arquivos de documentação do port são descritos na <link linkend="install-documentation">seção relevante</link>.</para> + + <para>Para fazer outras substituições, defina <varname>PLIST_SUB</varname> com uma lista de pares <literal><replaceable>VAR</replaceable>=<replaceable>VALOR</replaceable></literal> e as instâncias de <literal>%%<replaceable>VAR</replaceable>%%</literal> serão substituídas por <replaceable>VALOR</replaceable> no <filename>pkg-plist</filename>.</para> + + <para>Por exemplo, se um port instalar muitos arquivos em um subdiretório específico da versão, use um placeholder para a versão de modo que o <filename>pkg-plist</filename> não precise ser gerado novamente toda vez que o port é atualizado. Por exemplo:</para> + + <programlisting>OCTAVE_VERSION= ${PORTREVISION} +PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting> + + <para>no <filename>Makefile</filename> e use <literal>%%OCTAVE_VERSION%%</literal> onde quer que a versão apareça em <filename>pkg-plist</filename>. Quando o port é atualizado, não será necessário editar dezenas (ou em alguns casos, centenas) de linhas no <filename>pkg-plist</filename>.</para> + + <para>Se os arquivos são instalados condicionalmente pelas opções definidas no port, a maneira usual de lidar com isso é prefixando as linhas <filename>pkg-plist</filename> com <literal>%%OPT%%</literal> para linhas necessárias quando a opção está ativada ou <literal>%%NO_OPT%%</literal> quando a opção está desativada e adicionando <literal>OPTIONS_SUB=yes</literal> ao <filename>Makefile</filename>. Veja <xref linkend="options_sub"/> para mais informações.</para> + + <para>Por exemplo, se houver arquivos que são instalados apenas quando a opção <literal>X11</literal> está ativada, e o <filename>Makefile</filename> tem:</para> + + <programlisting>OPTIONS_DEFINE= X11 +OPTIONS_SUB= yes</programlisting> + + <para>No <filename>pkg-plist</filename>, insira <literal>%%X11%%</literal> no início das linhas que serão instaladas apenas quando a opção estiver habilitada, assim:</para> + + <programlisting>%%X11%%bin/foo-gui</programlisting> + + <para>Esta substituição será feita entre os targets <buildtarget>pre-install</buildtarget> e <buildtarget>do-install</buildtarget>, lendo a partir do <filename>PLIST</filename> e escrevendo em <filename>TMPPLIST</filename> (padrão:<filename>WRKDIR/.PLIST.mktmp</filename>). Então, se o port gera o <filename>PLIST</filename> na hora da compilação, faça isso em ou antes do <buildtarget>pre-install</buildtarget>. Além disso, se o port precisar editar o arquivo resultante, faça-o em <buildtarget>post-install</buildtarget> em um arquivo chamado <filename>TMPPLIST</filename>.</para> + + <para>Outra maneira de modificar a lista de empacotamento de um port é baseada na configuração das variáveis<varname>PLIST_FILES</varname> e <varname>PLIST_DIRS</varname>. O valor de cada variável é considerado como uma lista de nomes de caminho para gravar no <filename>TMPPLIST</filename> junto com conteúdo do <filename>PLIST</filename>. Enquanto os nomes listados no <varname>PLIST_FILES</varname> e <varname>PLIST_DIRS</varname> estão sujeitos a substituição do <literal>%%<replaceable>VAR</replaceable>%%</literal> conforme descrito acima, é melhor usar o <literal>${<replaceable>VAR</replaceable>}</literal> diretamente. Exceto por isso, os nomes contidos no <varname>PLIST_FILES</varname> aparecerão inalterados na lista final de packing, enquanto o <literal>@dir</literal> será anexado aos nomes do <varname>PLIST_DIRS</varname>. Para fazer efeito, o <varname>PLIST_FILES</varname> e o <varname>PLIST_DIRS</varname> devem ser definidos antes que o <filename>TMPPLIST</filename> seja escrito, isto é, no <buildtarget>pre-install</buildtarget> ou antes.</para> + + <para>De vez em quando, usar <varname>OPTIONS_SUB</varname> não é o suficiente. Nesses casos, adicionar uma <literal><replaceable>TAG</replaceable></literal> para <varname>PLIST_SUB</varname> dentro do <filename>Makefile</filename> com um valor especial <literal>@comment</literal>, faz as ferramentas de pacote ignorar a linha. Por exemplo, se alguns arquivos são instalados apenas quando a opção <literal>X11</literal> está habilitada e a arquitetura é <literal>i386</literal>:</para> + + <programlisting>.include <bsd.port.pre.mk> + +.if ${PORT_OPTIONS:MX11} && ${ARCH} == "i386" +PLIST_SUB+= X11I386="" +.else +PLIST_SUB+= X11I386="@comment " +.endif</programlisting> + + </sect1> + + <sect1 xml:id="plist-cleaning"> + <title>Diretórios Vazios</title> + + <sect2 xml:id="plist-dir-cleaning"> + <title>Limpando Diretórios Vazios</title> + + <para>Ao ser desinstalado, um port deve remover os diretórios vazios que ele criou. A maioria desses diretórios são removidos automaticamente pelo <citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>8</manvolnum></citerefentry>, mas para os diretórios criados fora do <filename>${PREFIX}</filename>, ou diretórios vazios, mais alguns passos precisam ser feitos. Isso geralmente é realizando adicionando entradas <literal>@dir</literal> para esses diretórios.Os subdiretórios devem ser excluídos antes de excluir os diretórios pai.</para> + + <programlisting>[...] +@dir /var/games/oneko/saved-games +@dir /var/games/oneko</programlisting> + </sect2> + + <sect2 xml:id="plist-dir-empty"> + <title>Criando Diretórios Vazios</title> + + <para>Os diretórios vazios criados durante a instalação do port precisam de atenção especial. Eles devem estar presentes quando o pacote é criado. Se eles não forem criados pelo código do port, crie-os no <filename>Makefile</filename>:</para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${PREFIX}/some/directory</programlisting> + + <para>Adicione o diretório ao <filename>pkg-plist</filename> como qualquer outro. Por exemplo:</para> + + <programlisting>@dir some/directory</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="plist-config"> + <title>Arquivos de Configuração</title> + + <para>Se o port instalar arquivos de configuração em <filename>PREFIX/etc</filename> (ou em outro lugar) <emphasis>não</emphasis> liste-os em <filename>pkg-plist</filename>. Isso fará com que <command>pkg delete</command> remova os arquivos que foram cuidadosamente editados pelo usuário, e uma reinstalação irá eliminá-los.</para> + + <para>Em vez disso, instale arquivos de exemplo com uma extensão <filename><replaceable>filename</replaceable>.sample</filename>. A macro <literal>@sample</literal> automatiza isso, consulte <xref linkend="plist-keywords-sample"/> para entender o que ela faz exatamente. Para cada arquivo de exemplo, adicione uma entrada no <filename>pkg-plist</filename>:</para> + + <programlisting>@sample etc/orbit.conf.sample</programlisting> + + <para>Se houver uma boa razão para não instalar um arquivo de configuração por padrão, liste apenas o nome do arquivo de exemplo em <filename>pkg-plist</filename>, sem o <literal>@sample</literal> seguido por um espaço e adicione uma <link linkend="porting-message">mensagem</link> ressaltando que o usuário deve copiar e editar o arquivo antes que o software seja executado.</para> + + <tip> + <para>Quando um port instala sua configuração em um subdiretório de <filename>${PREFIX}/etc</filename>, usar <varname>ETCDIR</varname>, cujo padrão é <literal>${PREFIX}/etc/${PORTNAME}</literal>, pode ser substituído nos <filename>Makefile</filename> dos ports se houver uma convenção para o port usar algum outro diretório. A macro <literal>%%ETCDIR%%</literal> será usado em seu lugar em <filename>pkg-plist</filename></para> + </tip> + + <note> + <para>Os arquivos de configuração de exemplo devem sempre ter o sufixo <filename>.sample</filename>. Se, por algum motivo histórico, o uso do sufixo padrão não for possível ou se os arquivos de exemplo vierem de algum outro diretório, use esta construção:</para> + + <programlisting>@sample etc/orbit.conf-dist etc/orbit.conf</programlisting> + + <para>ou</para> + + <programlisting>@sample %%EXAMPLESDIR%%/orbit.conf etc/orbit.conf</programlisting> + + <para>O formato é <literal>@sample <replaceable>sample-file</replaceable> <replaceable>actual-config-file</replaceable></literal>.</para> + </note> + </sect1> + + <sect1 xml:id="plist-dynamic"> + <title>Lista de Pacotes Estática versus Dinâmica</title> + + <para>Uma <emphasis>lista de pacotes estáticos</emphasis> é uma lista de pacotes que está disponível na Coleção de Ports ou como <filename>pkg-plist</filename> (com ou sem substituição de variável), ou embutido no <filename>Makefile</filename> através do <varname>PLIST_FILES</varname> e do <varname>PLIST_DIRS</varname>. Mesmo se o conteúdo for gerado automaticamente por uma ferramenta ou um taget no Makefile <emphasis>antes</emphasis> da inclusão na Coleção de Ports por um committer (por exemplo, usando <command>make makeplist></command>), isso ainda é considerado uma lista estática, já que é possível examiná-la sem ter que baixar ou compilar o distfile.</para> + + <para>Uma <emphasis>lista de pacotes dinâmicos</emphasis> é uma lista de pacotes que é gerada no momento em que o port é compilado com base nos arquivos e diretórios que estão instalados. Não é possível examiná-lo antes que o código-fonte do aplicativo portado seja baixado e compilado, ou após executar um <literal>make clean</literal>.</para> + + <para>Embora o uso de listas de pacotes dinâmicos não seja proibido, os mantenedores devem usar listas de pacotes estáticos sempre que possível, já que isso permite aos usuários utilizar <citerefentry><refentrytitle>grep</refentrytitle><manvolnum>1</manvolnum></citerefentry> nos de ports disponíveis para descobrir, por exemplo, qual port instala um determinado arquivo. Listas dinâmicas devem ser usadas principalmente para ports complexos onde a lista de pacotes muda drasticamente com base nos recursos opcionais do port (e assim manter uma lista de pacotes estática é impraticável), ou ports que alteram a lista de pacotes com base na versão do software dependente usado. Por exemplo, ports que geram documentos com <application>Javadoc</application>.</para> + </sect1> + + <sect1 xml:id="plist-autoplist"> + <title>Criação Automatizada da Lista de Pacotes</title> + + <para>Primeiro, verifique se o port está quase completo, faltando apenas o <filename>pkg-plist</filename>. Executar o comando <command>make makeplist</command> irá mostrar um exemplo para o <filename>pkg-plist</filename>. A saída do <buildtarget>makeplist</buildtarget> deve ser checada duas vezes quanto à correção, pois ela tenta adivinhar automaticamente algumas coisas e pode errar.</para> + + <para>Os arquivos de configuração do usuário devem ser instalados como <filename><replaceable>filename</replaceable>.sample</filename>, como é descrito em <xref linkend="plist-config"/>. O <filename>info/dir</filename> não deve ser listado e entradas apropriadas <filename>install-info</filename> devem ser adicionadas conforme a seção <link linkend="makefile-info">arquivos de informação</link>. Quaisquer bibliotecas instaladas pelo port devem ser listadas conforme especificado na seção <link linkend="porting-shlibs">bibliotecas compartilhadas</link>.</para> + + <sect2 xml:id="plist-autoplist-regex"> + <title>Expansão do <varname>PLIST_SUB</varname> com Expressões Regulares</title> + + <para>As strings a serem substituídas às vezes precisam ser muito específicas para evitar substituições indesejadas. Esse é um problema comum com valores mais curtos.</para> + + <para>Para resolver este problema, para cada <literal><replaceable>PLACEHOLDER</replaceable>=<replaceable>value</replaceable></literal>, um <literal><replaceable>PLACEHOLDER</replaceable>_regex =<replaceable>regex</replaceable></literal> pode ser definido, com o <replaceable>regex</replaceable> do <literal><replaceable>value</replaceable></literal> correspondendo mais precisamente.</para> + + <example xml:id="plist-autoplist-regex-ex1"> + <title>Usando PLIST_SUB com Expressões Regulares</title> + + <para>Os ports <application>Perl</application> podem instalar arquivos dependentes da arquitetura em uma árvore específica. No FreeBSD para facilitar a portabilidade, esta árvore é chamada de <literal>mach</literal>. Por exemplo, um port que instala um arquivo cujo caminho contém <literal>mach</literal> poderia ter essa parte da sequência do caminho substituída pelos valores incorretos. Considere este <filename>Makefile</filename>:</para> + + <programlisting>PORTNAME= Machine-Build +DISTVERSION= 1 +CATEGORIES= devel perl5 +MASTER_SITES= CPAN +PKGNAMEPREFIX= p5- + +MAINTAINER= perl@FreeBSD.org +COMMENT= Building machine + +USES= perl5 +USE_PERL5= configure + +PLIST_SUB= PERL_ARCH=mach</programlisting> + + <para>Os arquivos instalados pelo port são:</para> + + <programlisting>/usr/local/bin/machine-build +/usr/local/lib/perl5/site_perl/man/man1/machine-build.1.gz +/usr/local/lib/perl5/site_perl/man/man3/Machine::Build.3.gz +/usr/local/lib/perl5/site_perl/Machine/Build.pm +/usr/local/lib/perl5/site_perl/mach/5.20/Machine/Build/Build.so</programlisting> + + <para>Executar o <command>make makeplist</command> gera incorretamente:</para> + + <programlisting>bin/<emphasis>%%PERL_ARCH%%</emphasis>ine-build +%%PERL5_MAN1%%/<emphasis>%%PERL_ARCH%%</emphasis>ine-build.1.gz +%%PERL5_MAN3%%/Machine::Build.3.gz +%%SITE_PERL%%/Machine/Build.pm +%%SITE_PERL%%/%%PERL_ARCH%%/%%PERL_VER%%/Machine/Build/Build.so</programlisting> + + <para>Altere a linha <varname>PLIST_SUB</varname> do <filename>Makefile</filename> para:</para> + + <programlisting>PLIST_SUB= PERL_ARCH=mach \ + PERL_ARCH_regex=\bmach\b</programlisting> + + <para>Agora o <command>make makeplist</command> gera corretamente:</para> + + <programlisting>bin/machine-build +%%PERL5_MAN1%%/machine-build.1.gz +%%PERL5_MAN3%%/Machine::Build.3.gz +%%SITE_PERL%%/Machine/Build.pm +%%SITE_PERL%%/%%PERL_ARCH%%/%%PERL_VER%%/Machine/Build/Build.so</programlisting> + </example> + </sect2> + </sect1> + + <sect1 xml:id="plist-keywords"> + <title>Expandindo a Lista de Pacotes com Keywords</title> + + <para>Todas as keywords também podem ter argumentos opcionais entre parênteses. Os argumentos são owner, group e mode. Esse argumento é usado no arquivo ou diretório referenciado. Para alterar o dono, o grupo e o modo de um arquivo de configuração, use:</para> + + <programlisting>@sample(games,games,640) etc/config.sample</programlisting> + + <para>Os argumentos são opcionais. Se apenas o grupo e o modo precisarem ser alterados, use:</para> + + <programlisting>@sample(,games,660) etc/config.sample</programlisting> + + <warning> + <para xml:lang="en">If a keyword is used on an <link linkend="makefile-options">optional</link> entry, it must to + be added after the helper:</para> + + <programlisting>%%FOO%%@sample etc/orbit.conf.sample</programlisting> + + <para xml:lang="en">This is because the options plist helpers are used to + comment out the line, so they need to be put first. See <xref linkend="options_sub"/> for more information.</para> + </warning> + + <!-- + Keywords up-to-date with r381632. + Try and keep the keywords alphanumerically sorted. + --> + + <sect2 xml:id="plist-keywords-desktop-file-utils"> + <title><literal>@desktop-file-utils</literal></title> + + <para>Irá executar o <command>update-desktop-database -q</command> após a instalação e desinstalação. <emphasis>Nunca</emphasis> use diretamente, adicione <link linkend="uses-desktop-file-utils"><literal>USES=utilitários de arquivo de desktop</literal></link> ao <filename>Makefile</filename>.</para> + </sect2> + + <sect2 xml:id="plist-keywords-fc"> + <title><literal>@fc</literal> <replaceable>directory</replaceable></title> + + <para>Adiciona uma entrada <literal>@dir</literal> para o diretório passado como um argumento, e executa <command>fc-cache -fs</command> nesse diretório após a instalação e desinstalação.</para> + </sect2> + + <sect2 xml:id="plist-keywords-fcfontsdir"> + <title><literal>@fcfontsdir</literal> <replaceable>directory</replaceable></title> + + <para>Adiciona uma entrada <literal>@dir</literal> para o diretório passado como um argumento, e executa <command>fc-cache -fs</command>, <command>mkfontscale</command> e <command>mkfontdir</command> nesse diretório após a instalação e desinstalação. Além disso, na desinstalação, ele remove os arquivos de cache <filename>fonts.scale</filename> e <filename>fonts.dir</filename>, se estiverem vazios. Esta keyword é equivalente a adicionar o diretório <link linkend="plist-keywords-fc"><literal>@fc</literal><replaceable/></link> e o diretório <link linkend="plist-keywords-fontsdir"><literal>@fontsdir</literal><replaceable/></link>.</para> + </sect2> + + <sect2 xml:id="plist-keywords-fontsdir"> + <title><literal>@fontsdir</literal> <replaceable>directory</replaceable></title> + + <para>Adiciona um entrada <literal>@dir</literal> para o diretório passado como um argumento, e executa <command>mkfontscale</command> e <command>mkfontdir</command> nesse diretório após a instalação e desinstalação. Além disso, na desinstalação, ele remove os arquivos de cache <filename>fonts.scale</filename> e <filename>fonts.dir</filename>, se estiverem vazios.</para> + </sect2> + + <sect2 xml:id="plist-keywords-glib-schemas"> + <title><literal>@glib-schemas</literal></title> + + <para>Executa <command>glib-compile-schemas</command> na instalação e desinstalação.</para> + </sect2> + + <sect2 xml:id="plist-keywords-info"> + <title><literal>@info</literal> <replaceable>file</replaceable></title> + + <para>Adiciona o arquivo passado como argumento ao plist e atualiza o índice do documento info na instalação e desinstalação. Além disso, ele remove o índice se estiver vazio na desinstalação. Isso nunca deve ser usado manualmente, mas sempre <varname>INFO</varname>. Veja <xref linkend="makefile-info"/> para maiores informações.</para> + </sect2> + + <sect2 xml:id="plist-keywords-kld"> + <title><literal>@kld</literal> <replaceable>directory</replaceable></title> + + <para>Executa o <command>kldxref</command> no diretório na instalação e desinstalação. Além disso, na desinstalação, ele removerá o diretório se estiver vazio.</para> + </sect2> + + <sect2 xml:id="plist-keywords-rmtry"> + <title><literal>@rmtry</literal> <replaceable>file</replaceable></title> + + <para>O arquivo será removido na desinstalação, e não dará um erro se o arquivo não estiver lá.</para> + </sect2> + + <sect2 xml:id="plist-keywords-sample"> + <title><literal>@sample</literal> <replaceable>file</replaceable>[<replaceable>file</replaceable>] </title> + + <para>Isso é usado para lidar com a instalação de arquivos de configuração, através de arquivos de exemplo empacotados com o pacote. O arquivo <quote>atual</quote>, não-amostra, ou é o segundo nome do arquivo, se presente, ou o primeiro nome de arquivo sem a extensão <filename>.sample</filename>.</para> + + <para>Isso faz três coisas. Primeiro, adiciona o primeiro arquivo passado como argumento, o arquivo de exemplo, ao plist. Então, na instalação, se o arquivo real não for encontrado, copia o arquivo de exemplo para o arquivo real. E, finalmente, na desinstalação, remove o arquivo atual se ele não tiver sido modificado. Veja <xref linkend="plist-config"/> para maiores informações.</para> + </sect2> + + <sect2 xml:id="plist-keywords-shared-mime-info"> + <title><literal>@shared-mime-info</literal> <replaceable>directory</replaceable></title> + + <para>Executa <command>update-mime-database</command> no diretório na instalação e desinstalação.</para> + </sect2> + + <sect2 xml:id="plist-keywords-shell"> + <title><literal>@shell</literal> <replaceable>file</replaceable></title> + + <para>Adiciona o arquivo passado como argumento ao plist.</para> + + <para>Na instalação, adiciona o caminho completo do <replaceable>file</replaceable> em <filename>/etc/shells</filename>, certificando-se que não é adicionado duas vezes. Na desinstalação, remove-o de <filename>/etc/shells</filename>.</para> + </sect2> + + <sect2 xml:id="plist-keywords-terminfo"> + <title><literal>@terminfo</literal></title> + + <para>Não use sozinho. Se o port for instalar arquivos <filename><replaceable>*</replaceable>.terminfo</filename>, adicione <link linkend="uses-terminfo">USES=terminfo</link> no seu <filename>Makefile</filename>.</para> + + <para>Na instalação e desinstalação, se o <command>tic</command> estiver presente, atualize o <filename>${PREFIX}/share/misc/terminfo.db</filename> a partir dos arquivos <filename><replaceable>*</replaceable>.terminfo</filename> disponíveis em <filename>${PREFIX}/share/misc</filename></para> + </sect2> + + <sect2 xml:id="plist-keywords-base"> + <title>Keywords Básicas</title> + + <para>Existem algumas keywords que são codificadas e documentadas em <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Por uma questão de completude, elas também estão documentadas aqui.</para> + + <sect3 xml:id="plist-keywords-base-empty"> + <title><literal>@</literal> [<replaceable>file</replaceable>]</title> + + <para>A keyword vazia é um espaço reservado para ser usado quando o proprietário, grupo ou modo do arquivo precisam ser alterados. Por exemplo, para definir o grupo de um arquivo como <literal>games</literal> e adicionar o bit setgid, adicione:</para> + + <programlisting>@(,games,2755) sbin/daemon</programlisting> + </sect3> + + <sect3 xml:id="plist-keywords-base-exec"> + <title><literal>@preexec</literal> <replaceable>command</replaceable>, <literal>@postexec</literal> <replaceable>command</replaceable>, <literal>@preunexec</literal> <replaceable>command</replaceable>, <literal>@postunexec</literal> <replaceable>command</replaceable></title> + + <para>Executa o <replaceable>command</replaceable> como parte do processo de instalação ou desinstalação.</para> + + <variablelist> + <varlistentry> + <term><literal>@preexec</literal> <replaceable>command</replaceable></term> + + <listitem> + <para>Executar o <replaceable>command</replaceable> como parte dos scripts <filename>pre-install</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>@postexec</literal> <replaceable>command</replaceable></term> + + <listitem> + <para>Executar o <replaceable>command</replaceable> como parte dos scripts <filename>post-install</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>@preunexec</literal> <replaceable>command</replaceable></term> + + <listitem> + <para>Executar o <replaceable>command</replaceable> como parte dos scripts <filename>pre-deinstall</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>@postunexec</literal> <replaceable>command</replaceable></term> + + <listitem> + <para>Executar o <replaceable>command</replaceable> como parte dos scripts <filename>post-deinstall</filename>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>E se o <replaceable>command</replaceable> contém qualquer uma dessas sequências em algum lugar, elas são expandidas em linha. Para estes exemplos, assuma que <literal>@cwd</literal> está configurado para <filename>/usr/local</filename> e o último arquivo extraído foi <filename>bin/emacs</filename>.</para> + + <variablelist> + <varlistentry> + <term><literal>%F</literal></term> + + <listitem> + <para>Expandir para o último nome de arquivo extraído (conforme especificado). No caso do exemplo <filename>bin/emacs</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>%D</literal></term> + <listitem> + <para>Expandir para o prefixo do diretório atual, como definido no <literal>@cwd</literal>. No caso do exemplo <filename>/usr/local</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>%B</literal></term> + + <listitem> + <para>Expandir para o nome de base do nome completo do arquivo, ou seja, o prefixo do diretório atual mais o último arquivo, menos o nome do arquivo final. No exemplo, isso seria <filename>/usr/local/bin</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>%f</literal></term> + + <listitem> + <para>Expandir para a parte do nome do arquivo do nome totalmente qualificado, ou o inverso de <literal>%B</literal>. No caso do exemplo, <filename>emacs</filename>.</para> + </listitem> + </varlistentry> + </variablelist> + + <important> + <para>Essas keywords estão aqui para ajudá-lo a configurar o pacote para que ele esteja tão pronto quanto possível. Elas <emphasis>não devem</emphasis> ser abusadas para iniciar serviços, interromper serviços ou executar quaisquer outros comandos que modificarão o sistema em execução.</para> + </important> + </sect3> + + <sect3 xml:id="plist-keywords-base-mode"> + <title><literal>@mode</literal> <replaceable>mode</replaceable></title> + + <para>Define a permissão padrão para todos os arquivos extraídos posteriormente para <replaceable>mode</replaceable>. O formato é o mesmo usado por <citerefentry><refentrytitle>chmod</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Use sem um argumento para voltar às permissões padrão (modo do arquivo enquanto estava sendo empacotado).</para> + + <important> + <para>Este deve ser um modo numérico, como <literal>644</literal>, <literal>4755</literal> ou <literal>600</literal>. Não pode ser um modo relativo como<literal>u+s</literal>.</para> + </important> + </sect3> + + <sect3 xml:id="plist-keywords-base-owner"> + <title><literal>@owner</literal> <replaceable>user</replaceable></title> + + <para>Define a propriedade padrão para todos os arquivos subsequentes para <replaceable>user</replaceable>. Use sem um argumento para voltar à propriedade padrão (<systemitem class="username">root</systemitem>).</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-group"> + <title><literal>@group</literal> <replaceable>group</replaceable></title> + + <para>Define a propriedade de grupo padrão para todos os arquivos subsequentes para <replaceable>group</replaceable>. Use sem um argumento para retornar à propriedade do grupo padrão (<systemitem class="groupname">wheel</systemitem>).</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-comment"> + <title><literal>@comment</literal> <replaceable>string</replaceable></title> + + <para>Esta linha é ignorada no momento de empacotar.</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-dir"> + <title><literal>@dir</literal> <replaceable>directory</replaceable></title> + + <para>Declara o nome do diretório. Por padrão, os diretórios criados sob <varname>PREFIX</varname> por uma instalação de pacote são automaticamente removidos. Use isto quando um diretório vazio sob <varname>PREFIX</varname> precisa ser criado ou quando o diretório precisa ter proprietário, grupo ou modo não padrão. Diretórios fora de <varname>PREFIX</varname> precisam ser registrados. Por exemplo, <filename>/var/db/${PORTNAME}</filename> precisa ter uma entrada <literal>@dir</literal> enquanto <filename>${PREFIX}/share/${PORTNAME}</filename> não, se contiver arquivos ou usar o proprietário, grupo e modo padrão.</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-exec-deprecated"> + <title><literal>@exec</literal> <replaceable>command</replaceable>, <literal>@unexec</literal> <replaceable>command</replaceable> (Descontinuado)</title> + + <para>Executa o <replaceable>command</replaceable> como parte do processo de instalação ou desinstalação. Por favor, use <xref linkend="plist-keywords-base-exec"/> no lugar.</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-dirrm"> + <title><literal>@dirrm</literal> <replaceable>directory</replaceable> (Descontinuado)</title> + + <para>Declara o nome do diretório a ser excluído na desinstalação. Por padrão, os diretórios criados sob <varname>PREFIX</varname> por uma instalação de pacote são excluídos quando o pacote é desinstalado.</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-dirrmtry"> + <title><literal>@dirrmtry</literal> <replaceable>directory</replaceable> (Descontinuado)</title> + + <para>Declara o nome do diretório a ser removido, como para a keyword <literal>@dirrm</literal>, mas não emite um aviso se o diretório não puder ser removido.</para> + </sect3> + </sect2> + + <sect2 xml:id="plist-keywords-creating-new"> + <title>Criando Novas Keywords</title> + + <para>Os arquivos da lista de pacotes podem ser estendidos por keywords definidas no diretório <filename>${PORTSDIR}/Keywords</filename>. As configurações de cada keyword são armazenadas em um arquivo <acronym>UCL</acronym> chamado <filename><replaceable>keyword</replaceable>.ucl</filename>. O arquivo deve conter pelo menos uma destas seções:</para> + + <itemizedlist> + <listitem> + <para><literal>attributes</literal></para> + </listitem> + + <listitem> + <para><literal>action</literal></para> + </listitem> + + <listitem> + <para><literal>pre-install</literal></para> + </listitem> + + <listitem> + <para><literal>post-install</literal></para> + </listitem> + + <listitem> + <para><literal>pre-deinstall</literal></para> + </listitem> + + <listitem> + <para><literal>post-deinstall</literal></para> + </listitem> + + <listitem> + <para><literal>pre-upgrade</literal></para> + </listitem> + + <listitem> + <para><literal>post-upgrade</literal></para> + </listitem> + </itemizedlist> + + <sect3 xml:id="plist-keywords-attributes"> + <title><literal>attributes</literal></title> + + <para>Altera o dono, grupo ou modo usado pela keyword. Contém uma matriz associativa em que as chaves possíveis são <literal>owner</literal>, <literal>group</literal> e <literal>mode</literal>. Os valores são, respectivamente, um nome de usuário, um nome de grupo e um modo de arquivo. Por exemplo:</para> + + <programlisting>attributes: { owner: "games", group: "games", mode: 0555 }</programlisting> + </sect3> + + <sect3 xml:id="plist-keywords-action"> + <title><literal>action</literal></title> + + <para>Define o que acontece com o parâmetro da keyword. Contém uma matriz onde os valores possíveis são:</para> + + <variablelist> + <varlistentry> + <term><literal>setprefix</literal></term> + + <listitem> + <para>Define o prefixo para as próximas entradas do plist.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>dir</literal></term> + + <listitem> + <para>Registra um diretório para ser criado na instalação e removido na desinstalação.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>dirrm</literal></term> + + <listitem> + <para>Registra um diretório a ser excluído na desinstalação. Descontinuado.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>dirrmtry</literal></term> + + <listitem> + <para>Registra um diretório para tentar deletar na desinstalação. Descontinuado.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>file</literal></term> + + <listitem> + <para>Registra um arquivo.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>setmode</literal></term> + + <listitem> + <para>Define o modo para as próximas entradas do plist.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>setowner</literal></term> + + <listitem> + <para>Define o dono para as próximas entradas do plist.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>setgroup</literal></term> + + <listitem> + <para>Define o grupo para as próximas entradas do plist.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>comment</literal></term> + + <listitem> + <para>Não faz nada, é o equivalente a não entrar em uma seção <literal>action</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ignore_next</literal></term> + + <listitem> + <para>Ignora a próxima entrada no plist.</para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 xml:id="plist-keywords-arguments"> + <title><literal>arguments</literal></title> + + <para>Se definido para <literal>true</literal>, adiciona manipulação de argumentos, dividindo toda a linha, <literal>%@</literal>, em argumentos numerados,<literal>%1</literal>, <literal>%2</literal>, e assim por diante. Por exemplo, para esta linha:</para> + + <programlisting>@foo some.content other.content</programlisting> + + <para><literal>%1</literal> e <literal>%2</literal> irão conter:</para> + + <programlisting>some.content +other.content</programlisting> + + <para>Também afeta como a entrada <link linkend="plist-keywords-action"><literal>action</literal></link> funciona. Quando há mais de um argumento, o número do argumento deve ser especificado. Por exemplo:</para> + + <programlisting>actions: [file(1)]</programlisting> + </sect3> + + <sect3 xml:id="plist-keywords-pre-post"> + <title><literal>pre-install</literal>, <literal>post-install</literal>, <literal>pre-deinstall</literal>, <literal>post-deinstall</literal>, <literal>pre-upgrade</literal>, <literal>post-upgrade</literal></title> + + <para>Essas keywords contêm um script <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> a ser executado antes ou depois da instalação, desinstalação, ou atualização do pacote. Além do habitual placeholder <literal>@exec</literal><literal>%<replaceable>foo</replaceable></literal> descrito em <xref linkend="plist-keywords-base-exec"/>, há um novo <literal>%@</literal>, que representa o argumento da keyword.</para> + </sect3> + + <sect3 xml:id="plist-keywords-examples"> + <title>Exemplos de Keywords Customizadas</title> + + <example xml:id="plist-keywords-fc-example"> + <title>Exemplo de uma Keyword <literal>@dirrmtryecho</literal></title> + + <para>Esta keyword faz duas coisas, adiciona uma linha <literal>@dirrmtry <replaceable>directory</replaceable></literal> na lista de empacotamento, e escreve no log quando o diretório é removido ao desinstalar o pacote.</para> + + <programlisting>actions: [dirrmtry] +post-deinstall: <<EOD + echo "Directory %D/%@ removed." +EOD</programlisting> + </example> + + <example xml:id="plist-keywords-sample-example"> + <title>Exemplo na vida real, como o <literal>@sample</literal> é implementado</title> + + <para>Esta keyword faz três coisas. Ela adiciona o primeiro <replaceable>filename</replaceable> passado como um argumento para <literal>@sample</literal> na lista de empacotamento, ele adiciona instruções ao script de <literal>post-install</literal> para copiar o exemplo para o arquivo de configuração real, se ele ainda não existir, e adiciona instruções ao script <literal>post-deinstall</literal> para remover o arquivo de configuração se ele não tiver sido modificado.</para> + + <programlisting>actions: [file(1)] +arguments: true +post-install: <<EOD + case "%1" in + /*) sample_file="%1" ;; + *) sample_file="%D/%1" ;; + esac + target_file="${sample_file%.sample}" + set -- %@ + if [ $# -eq 2 ]; then + target_file=${2} + fi + case "${target_file}" in + /*) target_file="${target_file}" ;; + *) target_file="%D/${target_file}" ;; + esac + if ! [ -f "${target_file}" ]; then + /bin/cp -p "${sample_file}" "${target_file}" && \ + /bin/chmod u+w "${target_file}" + fi +EOD +pre-deinstall: <<EOD + case "%1" in + /*) sample_file="%1" ;; + *) sample_file="%D/%1" ;; + esac + target_file="${sample_file%.sample}" + set -- %@ + if [ $# -eq 2 ]; then + set -- %@ + target_file=${2} + fi + case "${target_file}" in + /*) target_file="${target_file}" ;; + *) target_file="%D/${target_file}" ;; + esac + if cmp -s "${target_file}" "${sample_file}"; then + rm -f "${target_file}" + else + echo "You may need to manually remove ${target_file} if it is no longer needed." + fi +EOD</programlisting> + </example> + </sect3> + </sect2> + </sect1> +</chapter> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter version="5.0" xml:id="pkg-files"> + + <title><filename>pkg-*</filename></title> + + <para>Existem alguns truques que ainda não foram mencionamos sobre os arquivos <filename>pkg-<replaceable>*</replaceable></filename> que são úteis às vezes.</para> + + <sect1 xml:id="porting-message"> + <title><filename>pkg-message</filename></title> + + <para>Para exibir uma mensagem quando o pacote é instalado, coloque a mensagem em <filename>pkg-message</filename>. Esse recurso é geralmente útil para exibir etapas adicionais de instalação a serem executadas após o <command>pkg-install</command> ou para exibir informações de licenciamento.</para> + + <para>Quando algumas linhas sobre os knobs ou avisos de tempo de compilação tiverem que ser exibidos, use <varname>ECHO_MSG</varname>. O <filename>pkg-message</filename> é apenas para etapas de pós-instalação. Da mesma forma, a distinção entre <varname>ECHO_MSG</varname> é que ele serve para imprimir texto informativo na tela e o <varname>ECHO_CMD</varname> é serve para fazer pipelining de comandos:</para> + + <programlisting>update-etc-shells: + @${ECHO_MSG} "updating /etc/shells" + @${CP} /etc/shells /etc/shells.bak + @( ${GREP} -v ${PREFIX}/bin/bash /etc/shells.bak; \ + ${ECHO_CMD} ${PREFIX}/bin/bash) >/etc/shells + @${RM} /etc/shells.bak</programlisting> + + <note> + <para>Não adicione uma entrada para o <filename>pkg-message</filename> ao <filename>pkg-plist</filename>.</para> + </note> + </sect1> + + <sect1 xml:id="pkg-install"> + <title><filename>pkg-install</filename></title> + + <para>Se o port precisa executar comandos quando o pacote binário é instalado com o <command>pkg add</command> ou com o <command>pkg install</command>, use o <filename>pkg-install</filename>. Este script será automaticamente adicionado ao pacote. Será executado duas vezes pelo <command>pkg</command>, a primeira vez como <literal>${SH} pkg-install ${PKGNAME} PRE-INSTALL</literal> antes que o pacote seja instalado e uma segunda vez como <literal>${SH} pkg-install ${PKGNAME} POST-INSTALL</literal> depois dele ter sido instalado. O valor de <literal>$2</literal> pode ser testado para determinar em que modo o script está sendo executado. A variável de ambiente <envar>PKG_PREFIX</envar> será definida para o diretório de instalação do pacote.</para> + + <important> + <para>Este script está aqui para ajudá-lo a configurar o pacote para que ele esteja tão pronto quanto possível para ser usado. Ele <emphasis>não deve</emphasis> ser abusado para iniciar serviços, interromper serviços ou executar quaisquer outros comandos que modificarão o sistema em execução no momento.</para> + </important> + </sect1> + + <sect1 xml:id="pkg-deinstall"> + <title><filename>pkg-deinstall</filename></title> + + <para>Este script é executado quando um pacote é removido.</para> + + <para>Este script será executado duas vezes pelo <command>pkg delete</command>. A primeira vez como <literal>${SH} pkg-deinstall ${PKGNAME} DEINSTALL</literal> antes que o port seja desinstalado e a segunda vez como <literal>${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL</literal> após o port ter sido desinstalado. O valor de <literal>$2</literal> pode ser testado para determinar em que modo o script está sendo executado. A variável de ambiente <envar>PKG_PREFIX</envar> será definida para o diretório de instalação do pacote.</para> + + <important> + <para>Este script está aqui para ajudá-lo a configurar o pacote para que ele esteja tão pronto quanto possível para ser usado. Ele <emphasis>não deve</emphasis> ser abusado para iniciar serviços, interromper serviços ou executar quaisquer outros comandos que modificarão o sistema em execução no momento.</para> + </important> + </sect1> + + <sect1 xml:id="pkg-names"> + <title xml:id="porting-pkgfiles">Mudando os nomes dos <filename>pkg-<replaceable>*</replaceable></filename></title> + + <para>Todos os nomes de <filename>pkg-<replaceable>*</replaceable></filename> são definidos usando variáveis que podem ser alteradas no <filename>Makefile</filename> se necessário. Isso é especialmente útil ao compartilhar os mesmos arquivos <filename>pkg-<replaceable>*</replaceable></filename> entre vários ports ou quando é necessário gravar em um desses arquivos. Veja <link linkend="porting-wrkdir">escrevendo em lugares que não o <varname>WRKDIR</varname></link> para entender por que é uma má ideia escrever diretamente no diretório que contém os arquivos <filename>pkg-<replaceable>*</replaceable></filename>.</para> + + <para>Aqui está uma lista de nomes de variáveis e seus valores padrão. (O valor padrão do <varname>PKGDIR</varname> é <varname>${MASTERDIR}</varname>).</para> + + <informaltable frame="none" pgwide="0"> + <tgroup cols="2"> + <thead> + <row> + <entry>Variável</entry> + <entry>Valor padrão</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>DESCR</varname></entry> + <entry><literal>${PKGDIR}/pkg-descr</literal></entry> + </row> + + <row> + <entry><varname>PLIST</varname></entry> + <entry><literal>${PKGDIR}/pkg-plist</literal></entry> + </row> + + <row> + <entry><varname>PKGINSTALL</varname></entry> + <entry><literal>${PKGDIR}/pkg-install</literal></entry> + </row> + + <row> + <entry><varname>PKGDEINSTALL</varname></entry> + <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry> + </row> + + <row> + <entry><varname>PKGMESSAGE</varname></entry> + <entry><literal>${PKGDIR}/pkg-message</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1 xml:id="using-sub-files"> + <title>Fazendo uso de <varname>SUB_FILES</varname> e <varname>SUB_LIST</varname></title> + + <para>O <varname>SUB_FILES</varname> e o <varname>SUB_LIST</varname> são úteis para valores dinâmicos em arquivos do port, como o <varname>PREFIX</varname> de instalação dentro do <filename>pkg-message</filename>.</para> + + <para>A <varname>SUB_FILES</varname> especifica uma lista de arquivos a serem modificados automaticamente. Cada <filename><replaceable>arquivo</replaceable></filename> na lista <varname>SUB_FILES</varname> deve ter um <filename>arquivo<replaceable>.in</replaceable> correspondente </filename> presente no <varname>FILESDIR</varname>. Uma versão modificada será criada como <filename>${WRKDIR}/<replaceable>arquivo</replaceable></filename>. Os arquivos definidos como um valor de <varname>USE_RC_SUBR</varname> são automaticamente adicionados ao <varname>SUB_FILES</varname>. Para os arquivos<filename>pkg-message</filename>, <filename>pkg-install</filename> e <filename>pkg-deinstall</filename>, a variável Makefile correspondente é automaticamente definida para apontar para a versão processada.</para> + + <para>A <varname>SUB_LIST</varname> é uma lista de pares <literal>VAR=VALUE</literal>. Para cada par, <literal>%%VAR%%</literal> será substituído por <literal>VALUE</literal> em cada arquivo listado em <varname>SUB_FILES</varname>. Vários pares comuns são definidos automaticamente: <varname>PREFIX</varname>, <varname>LOCALBASE</varname>, <varname>DATADIR</varname>, <varname>DOCSDIR</varname>, <varname>EXEMPLESDIR</varname>, <varname>WWWDIR</varname> e <varname>ETCDIR</varname>. Qualquer linha que comece com <literal>@Comment</literal> seguido por um espaço, será excluído dos arquivos resultantes após uma substituição de variável.</para> + + <para>Este exemplo substitui <literal>%%ARCH%%</literal> com a arquitetura do sistema em um <filename>pkg-message</filename>:</para> + + <programlisting>SUB_FILES= pkg-message +SUB_LIST= ARCH=${ARCH}</programlisting> + + <para>Note que para este exemplo, o <filename>pkg-message.in</filename> deve existir no <varname>FILESDIR</varname>.</para> + + <para>Exemplo de um bom <filename>pkg-message.in</filename>:</para> + + <programlisting>Now it is time to configure this package. +Copy %%PREFIX%%/share/examples/putsy/%%ARCH%%.conf into your home directory +as .putsy.conf and edit it.</programlisting> + </sect1> +</chapter> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="testing"> + + <title>Testando o Port</title> + + <sect1 xml:id="make-describe"> + <title>Executando <command>make describe</command></title> + + <para>Várias das ferramentas de manutenção de ports do FreeBSD, tal como o <citerefentry vendor="ports"><refentrytitle>portupgrade</refentrytitle><manvolnum>1</manvolnum></citerefentry>, conta com um banco de dados chamado <filename>/usr/ports/INDEX</filename> o qual mantém um registro de itens tais como as dependências do port. O <filename>INDEX</filename> é criado pelo <filename>ports/Makefile</filename> de nível superior através do comando <command>make index</command>, que desce em cada subdiretório dos ports e executa o comando <command>make describe</command> lá. Desta forma, se o <command>make describe</command> falhar em qualquer port, ninguém poderá gerar o <filename>INDEX</filename> e muitas pessoas rapidamente se tornarão infelizes.</para> + + <note> + <para>É importante poder gerar este arquivo independentemente das opções presentes no <filename>make.conf</filename> então evite fazer coisas como usar declarações <literal>.error</literal> quando (por exemplo) uma dependência não estiver satisfeita. (Veja <xref linkend="dads-dot-error"/>.</para> + </note> + + <para>E se o <command>make describe</command> produzir uma string em vez de uma mensagem de erro, provavelmente está tudo certo. Veja o <filename>bsd.port.mk</filename> para saber o significado da string gerada.</para> + + <para>Note também que rodar uma versão recente do <command>portlint</command> (conforme especificado na próxima seção) executará o <command>make describe</command> automaticamente.</para> + </sect1> + + <sect1 xml:id="testing-portlint"> + <title>Portlint</title> + + <para>Verifique o port com <link linkend="porting-portlint"><command>portlint</command></link> antes de submete-lo ou de fazer o seu commit. O <command>portlint</command> alerta sobre muitos erros comuns, tanto funcionais quanto de estilo. Para um novo (ou um repocopiado) port , <command>portlint -A</command> é o uso mais completo; para um port existente, <command>portlint -C</command> é suficiente.</para> + + <para>O <command>portlint</command> usa uma técnica heurística para tentar descobrir erros, pode produzir avisos falso-positivos. Além disso, ocasionalmente, algo que é sinalizado como um problema, pode não ter uma outra forma de ser realizado por limitações no framework dos ports. Em caso de dúvida, a melhor coisa a fazer é perguntar na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">Lista de discussão de ports do FreeBSD</link>.</para> + </sect1> + + <sect1 xml:id="testing-porttools"> + <title>Ferramentas do Ports</title> + + <para>O programa <package role="port">ports-mgmt/porttools</package> faz parte da Coleção de Ports.</para> + + <para>O <command>port</command> é o script front-end, que pode ajudar a simplificar o trabalho de teste. Sempre que um novo port ou uma atualização de um já existente precisar de teste, use <command>port test</command> para testar o port, incluindo a verificação <link linkend="testing-portlint"><command>portlint</command></link>. Este comando também detecta e lista todos os arquivos que não estão listados no <filename>pkg-plist</filename>. Por exemplo:</para> + + <screen><prompt>#</prompt> <userinput>port test /usr/ports/net/csup</userinput></screen> + </sect1> + + <sect1 xml:id="porting-prefix"> + <title><varname>PREFIX</varname> e <varname>DESTDIR</varname></title> + + <para><varname>PREFIX</varname> determina onde o port será instalado. O padrão é <filename>/usr/local</filename>, mas pode ser definido pelo usuário para um caminho personalizado como <filename>/opt</filename>. O port deve respeitar o valor dessa variável.</para> + + <para>O <varname>DESTDIR</varname>, se definido pelo usuário, determina o ambiente alternativo completo, geralmente uma jail ou um sistema instalado montado em outro local que não seja o <filename>/</filename>. Um port será realmente instalado no <filename>DESTDIR/PREFIX</filename>, e registrado no banco de dados de pacotes em <filename>DESTDIR/var/db/pkg</filename>. Como o <varname>DESTDIR</varname> é tratado automaticamente pela infraestrutura de ports com o <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Não há necessidade de modificações ou qualquer cuidado extra para escrever ports compatíveis com o <varname>DESTDIR</varname>.</para> + + <para>O valor de <varname>PREFIX</varname> será definido para <varname>LOCALBASE</varname> (o valor padrão é <filename>/usr/local</filename>). E se <varname>USE_LINUX_PREFIX</varname> estiver definido o <varname>PREFIX</varname> será <varname>LINUXBASE</varname> (o valor padrão é <filename>/compat/linux</filename>).</para> + + <para>Evitar o uso do caminho <filename>/usr/local</filename> codificado no fonte tornam o port muito mais flexível e capaz de atender às necessidades de outros sites. Muitas vezes, isso pode ser feito substituindo as ocorrências de <filename>/usr/local</filename> nos vários <filename>Makefile</filename>s dos ports por <literal>${PREFIX}</literal>. Essa variável é transmitida automaticamente para todos os estágios dos processos de compilação e instalação.</para> + + <para>Verifique se o aplicativo não está instalando arquivos em <filename>/usr/local</filename> ao invés de <varname>PREFIX</varname>. Um teste rápido para esses caminhos codificados é:</para> + + <screen><prompt>%</prompt> <userinput>make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen> + + <para>Se alguma coisa for instalada fora do <varname>PREFIX</varname>, o processo de criação de pacotes irá reclamar que não pode encontrar os arquivos.</para> + + <para>Além disso, vale a pena verificar o mesmo em relação ao suporte a diretórios stage (veja <xref linkend="staging"/>):</para> + + <screen><prompt>%</prompt> <userinput>make stage && make check-plist && make stage-qa && make package</userinput></screen> + + <itemizedlist> + <listitem> + <para>O <buildtarget>check-plist</buildtarget> verifica arquivos ausentes do plist e arquivos no plist que não são instalados pelo port.</para> + </listitem> + + <listitem> + <para>O <buildtarget>stage-qa</buildtarget> verifica problemas comuns como shebang incorretas, links simbólicos apontando para fora do diretório de stage, arquivos setuid e bibliotecas não removidas...</para> + </listitem> + </itemizedlist> + + <para>Esses testes não encontrarão caminhos codificados dentro dos arquivos do port, nem verificarão se o <varname>LOCALBASE</varname> está sendo usado para se referir corretamente a arquivos de outros ports. O port instalado temporariamente em <filename>/var/tmp/`make -V PORTNAME`</filename> deve ser testado quanto à operação correta para garantir que não haja problemas com os caminhos.</para> + + <para>O <varname>PREFIX</varname> não deve ser definido explicitamente em um <filename>Makefile</filename> do port. Usuários instalando o port podem ter definido a variável <varname>PREFIX</varname> para um local personalizado e o port deve respeitar essa configuração.</para> + + <para>Referencie programas e arquivos de outros ports com as variáveis mencionadas acima, não com nomes de caminho explícitos. Por exemplo, se o port exigir uma macro <literal>PAGER</literal> para ter o nome de caminho completo para o <command>less</command>, não use um caminho literal para <filename>/usr/local/bin/less</filename>. Em vez disso, use <literal>${LOCALBASE}</literal>:</para> + + <programlisting>-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> + + <para>O caminho com <varname>LOCALBASE</varname> é muito provável que ainda funcione se o administrador do sistema mudou toda a arvore <filename>/usr/local</filename> para algum outro lugar.</para> + + <tip> + <para>Todos esses testes são feitos automaticamente ao executar <command>poudriere testport</command> ou <command>poudriere bulk -t</command>. É altamente recomendável que cada contribuidor de ports instale e teste seus ports com ele. Veja <xref linkend="testing-poudriere"/> para maiores informações.</para> + </tip> + </sect1> + + <sect1 xml:id="testing-poudriere"> + <title><application>Poudriere</application></title> + + <para>Para um contribuidor de ports, o <application>Poudriere</application> é uma das mais importantes e úteis ferramentas de teste e compilação. Suas principais características incluem:</para> + + <itemizedlist> + <listitem> + <para>Compilação em massa de toda a árvore de ports, subconjuntos específicos da árvore de ports, ou um único port incluindo suas dependências</para> + </listitem> + + <listitem> + <para>Empacotamento automático do resultados de compilação</para> + </listitem> + + <listitem> + <para>Geração de arquivos de log de compilação por port</para> + </listitem> + + <listitem> + <para>Fornecer um repositório <citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>8</manvolnum></citerefentry> assinado</para> + </listitem> + + <listitem> + <para>Testar a compilação do port antes de enviar um patch para o rastreador de bugs do FreeBSD ou antes de fazer o commit para a árvore de ports</para> + </listitem> + + <listitem> + <para>Testar a compilação bem-sucedida de ports usando opções diferentes</para> + </listitem> + </itemizedlist> + + <para>Porque o <application>Poudriere</application> realiza a sua compilação em um ambiente de <citerefentry><refentrytitle>jail</refentrytitle><manvolnum>8</manvolnum></citerefentry> limpo e usa características do <citerefentry><refentrytitle>zfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, ele tem várias vantagens sobre os testes tradicionais no sistema host:</para> + + <itemizedlist> + <listitem> + <para>Ele não polui o ambiente do host: sem arquivos sobrando, sem remoções acidentais, sem alterações nos arquivos de configuração existentes.</para> + </listitem> + + <listitem> + <para>Ele verifica o <filename>pkg-plist</filename> para entradas ausentes ou supérfluas</para> + </listitem> + + <listitem> + <para>Committers de ports às vezes pedem um log do <application>Poudriere</application> juntamente com a apresentação de um patch para avaliar se o patch está pronto para integração na árvore de ports</para> + </listitem> + </itemizedlist> + + <para>Ele também é muito simples de configurar e usar, não tem dependências e será executado em qualquer versão suportada do FreeBSD. Esta seção mostra como instalar, configurar e executar o <application>Poudriere</application> como parte do fluxo de trabalho normal de um contribuidor de ports.</para> + + <para>Os exemplos nesta seção mostram um layout de arquivo padrão, como padrão no FreeBSD. Substitua quaisquer alterações locais de acordo. A árvore de ports, representada por <varname>${PORTSDIR}</varname>, está localizada em <filename>/usr/ports</filename>. Ambos <varname>${LOCALBASE}</varname> e <varname>${PREFIX}</varname> são <filename>/usr/local</filename> por padrão.</para> + + <sect2 xml:id="testing-poudriere-installing"> + <title>Instalando o <application>Poudriere</application></title> + + <para>O <application>Poudriere</application> está disponível na árvore de ports em <package role="port">ports-mgmt/poudriere</package>. Ele pode ser instalado usando o <citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>8</manvolnum></citerefentry> ou a partir do ports:</para> + + <screen><prompt>#</prompt> <userinput>pkg install poudriere</userinput></screen> + + <para>ou</para> + + <screen><prompt>#</prompt> <userinput>make -C /usr/ports/ports-mgmt/poudriere install clean</userinput></screen> + + <para>Há também uma versão de trabalho em andamento do <application>Poudriere</application> que acabará por se tornar o próximo release. Ele está disponível em <package role="port">ports-mgmt/poudriere-devel</package>. Esta versão de desenvolvimento é usada para as compilações oficiais de pacotes do FreeBSD, então é bem testada. Muitas vezes tem novos recursos interessantes. Um committer de ports desejará usar a versão de desenvolvimento porque é o que é usado na produção e possui todos os novos recursos que farão com que tudo esteja exatamente correto. Um colaborador não precisará necessariamente deles, pois as correções mais importantes são sempre incorporadas na versão release. A principal razão para o uso da versão de desenvolvimento para compilar os pacotes oficiais é porque é mais rápido, de uma forma que encurtará uma compilação completa de 18 horas para 17 horas ao usar um servidor de 32 <acronym>CPUs</acronym> high-end com 128GB de <acronym>RAM</acronym>. Essas otimizações não terão muita importância ao compilar ports em uma máquina desktop.</para> + + </sect2> + + <sect2 xml:id="testing-poudriere-setup"> + <title>Configurando o <application>Poudriere</application></title> + + <para>O port instala um arquivo de configuração padrão, o <filename>/usr/local/etc/poudriere.conf</filename>. Cada parâmetro é documentado no arquivo de configuração em <citerefentry vendor="ports"><refentrytitle>poudriere</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Aqui está um arquivo de configuração mínimo de exemplo:</para> + + <programlisting>ZPOOL=tank +ZROOTFS=/poudriere +BASEFS=/poudriere +DISTFILES_CACHE=/usr/ports/distfiles +RESOLV_CONF=/etc/resolv.conf +FREEBSD_HOST=ftp://ftp.freebsd.org +SVN_HOST=svn.FreeBSD.org</programlisting> + + <variablelist> + <varlistentry> + <term><varname>ZPOOL</varname></term> + + <listitem> + <para>O nome do pool de armazenamento do <acronym>ZFS</acronym> que o <application>Poudriere</application> deve usar. Deve ser listado na saída de <command>zpool status</command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ZROOTFS</varname></term> + + <listitem> + <para>A raiz dos sistemas de arquivos gerenciados do <application>Poudriere</application>. Esta entrada fará com que o <application>Poudriere</application> crie o sistema de arquivo <citerefentry><refentrytitle>zfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> sob <literal>tank/poudriere</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BASEFS</varname></term> + + <listitem> + <para>O ponto de montagem da raiz do sistema de arquivo <application>Poudriere</application>. Esta entrada fará com que o <application>Poudriere</application> monte o <literal>tank/poudriere</literal> no <literal>/poudriere</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DISTFILES_CACHE</varname></term> + + <listitem> + <para>Define onde os distfiles são armazenados. Neste exemplo, o <application>Poudriere</application> e o host compartilham o diretório de armazenamento dos distfiles. Isso evita o download de tarballs que já estão presentes no sistema.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RESOLV_CONF</varname></term> + + <listitem> + <para>Utiliza o <filename>/etc/resolv.conf</filename> do host dentro do jails para a resolução de <acronym>DNS</acronym>. Isso é necessário para que as jails possam resolver as <acronym>URLs</acronym> dos distfiles durante o download. Não é necessário ao usar um proxy. Consulte o arquivo de configuração padrão para a configuração de proxy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>FREEBSD_HOST</varname></term> + + <listitem> + <para>O servidor <acronym>FTP</acronym>/<acronym>HTTP</acronym> a ser usado quando as jails são instaladas a partir de versões do FreeBSD e atualizadas com o <citerefentry><refentrytitle>freebsd-update</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Escolha um servidor cuja localização esteja próxima, por exemplo, se a máquina estiver localizada na Austrália, use <literal>ftp.au.freebsd.org</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>SVN_HOST</varname></term> + + <listitem> + <para>O servidor de onde as jails são instaladas e atualizadas ao usar o <application>Subversion</application>. Também usado para a árvore de ports quando não estiver usando o <citerefentry><refentrytitle>portsnap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Mais uma vez, escolha um local próximo. Uma lista de espelhos oficiais do <application>Subversion</application> podem ser encontrados na seção sobre <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/svn.html#svn-mirrors"><application>Subversion</application></link> do Handbook do FreeBSD.</para> + </listitem> + </varlistentry> + </variablelist> + + </sect2> + + <sect2 xml:id="testing-poudriere-create-jails"> + <title>Criando <application>Poudriere</application> Jails</title> + + <para>Crie as jails de base que serão usadas pelo <application>Poudriere</application> para as compilações:</para> + + <screen><prompt>#</prompt> <userinput>poudriere jail -c -j 111Ramd64 -v 11.1-RELEASE -a amd64</userinput></screen> + + <para>Busca a versão <literal>11.1-RELEASE</literal> para <literal>amd64</literal> do servidor <acronym>FTP</acronym> dado por <varname>FREEBSD_HOST</varname> dentro do <filename>poudriere.conf</filename>, crie o sistema de arquivos com zfs em <literal>tank/poudriere/jails/111Ramd64</literal>, monta-o em <filename>/poudriere/jails/111Ramd64</filename> e extrai os tarballs <literal>11.1-RELEASE</literal> neste sistema de arquivos.</para> + + <screen><prompt>#</prompt> <userinput>poudriere jail -c -j 11i386 -v stable/11 -a i386 -m svn+https</userinput></screen> + + <para>Criado o <literal>tank/poudriere/jaulas/11i386</literal> monte-o em <filename>/poudriere/jails/11i386</filename>, então confira a dica do <application>Subversion</application> branch do <literal>FreeBSD-11-STABLE</literal> a partir do <literal>SVN_HOST</literal> dentro do <filename>poudriere.conf</filename> para dentro de <filename>/poudriere/jails/11i386/usr/src</filename>, e então complete um <buildtarget>buildworld</buildtarget> e instale-o em <filename>/poudriere/jails/11i386</filename>.</para> + + <tip> + <para>Se uma determinada revisão do <application>Subversion</application> é necessária, anexe ela à string de versão. Por exemplo:</para> + + <screen><prompt>#</prompt> <userinput>poudriere jail -c -j 11i386 -v stable/11@123456 -a i386 -m svn+https</userinput></screen> + </tip> + + <note> + <para>Embora seja possível compilar uma versão mais nova do FreeBSD em uma versão mais antiga, na maioria das vezes ela não irá executar. Por exemplo, se uma jail <literal>stable/11</literal> é necessária, o host terá que rodar <literal>stable/11</literal> também. Rodar <literal>11.0-RELEASE</literal> não é o suficiente.</para> + </note> + + <note> + <para>Para criar uma jail <application>Poudriere</application> para o <literal>12.0-CURRENT</literal>:</para> + + <screen><prompt>#</prompt> <userinput>poudriere jail -c -j 12amd64 -v head -a amd64 -m svn+https</userinput></screen> + + <para>Para executar uma jail <literal>12.0-CURRENT</literal> no <application>Poudriere</application> você deve estar rodando o <literal>12.0-CURRENT</literal>. Em geral, novos kernels podem ser compilados e executar jails mais antigas. Por exemplo, um kernel <literal>12.0-CURRENT</literal> pode compilar e executar uma jail <literal>11.1-STABLE</literal> no <application>Poudriere</application> se a opção de kernel <literal>COMPAT_FREEBSD11</literal> tiver sido compilada (habilitada por padrão na configuração do kernel <filename>GENERIC</filename> do <literal>12.0-CURRENT</literal>).</para> + </note> + + <caution> + <para>O protocolo padrão <literal>svn</literal> funciona normalmente, mas não é muito seguro. Usar <literal>svn+https</literal> juntamente com a verificação do fingerpprint <acronym>SSL</acronym> do servidor remoto é aconselhável. Isso garantirá que os arquivos usados para compilar a jail sejam de uma fonte confiável.</para> + </caution> + + <para>Uma lista de jails atualmente conhecidas pelo <application>Poudriere</application> podem ser mostradas com <command>poudriere jail -l</command>:</para> + + <screen><prompt>#</prompt> <userinput>poudriere jail -l</userinput> +JAILNAME VERSION ARCH METHOD +111Ramd64 11.1-RELEASE amd64 ftp +11i386 11.0-STABLE i386 svn+https</screen> + </sect2> + + + <sect2 xml:id="testing-poudriere-maintaining-jails"> + <title>Mantendo as Jails do <application>Poudriere</application> Atualizadas</title> + + <para>Gerenciar atualizações é muito simples. O comando:</para> + + <screen><prompt>#</prompt> <userinput>poudriere jail -u -j <replaceable>JAILNAME</replaceable></userinput></screen> + + <para>atualiza a jail especificada para a versão mais recente disponível. Para releases do FreeBSD, atualiza para o patchlevel mais recente com o <citerefentry><refentrytitle>freebsd-update</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Para versões do FreeBSD compiladas a partir do código fonte, atualiza para a revisão mais recente na branch do <application>Subversion</application>.</para> + + <tip> + <para>Para jails que empregam um método <literal>svn+<replaceable>*</replaceable></literal>, é útil adicionar <command>-J <replaceable>NumberOfParallelBuildJobs</replaceable></command> para acelerar a compilação aumentando o número de trabalhos de compilação paralelos utilizados. Por exemplo, se a máquina de compilação tiver 6 <acronym>CPU</acronym>s, use:</para> + + <screen><prompt>#</prompt> <userinput>poudriere jail -u -J 6 -j <replaceable>JAILNAME</replaceable></userinput></screen> + </tip> + </sect2> + + <sect2 xml:id="testing-poudriere-ports-tree"> + <title>Configurando a Árvores de Ports para Uso com o <application>Poudriere</application></title> + + <para>Existem várias maneiras de usar árvores de ports no <application>Poudriere</application>. A maneira mais direta é o <application>Poudriere</application> criar uma árvore de ports padrão para si mesmo:</para> + + <screen><prompt>#</prompt> <userinput>poudriere ports -c</userinput></screen> + + <para>Este comando cria o <literal>tank/poudriere/ports/default</literal>, monta-o em <filename>/poudriere/ports/default</filename> e o povoa usando o <citerefentry><refentrytitle>portsnap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Depois disso, ele é incluído na lista de árvores de ports conhecidas:</para> + + <screen><prompt>#</prompt> <userinput>poudriere ports -l</userinput> +PORTSTREE METHOD PATH +default portsnap /poudriere/ports/default</screen> + + <note> + <para>Note que a árvore de ports <quote>default</quote> é especial. Cada um dos comandos de compilação explicados posteriormente usará implicitamente essa árvore de ports, a menos que seja especificamente especificado de outra forma. Para usar outra árvore, adicione <command>-p <replaceable>treename</replaceable></command> aos comandos.</para> + </note> + + <para>Embora seja útil para compilações em massa regulares, ter esta árvore de ports padrão com o método <citerefentry><refentrytitle>portsnap</refentrytitle><manvolnum>8</manvolnum></citerefentry> pode não ser a melhor maneira de lidar com modificações locais para um contribuidor de ports. Assim como na criação dos jails, é possível usar um método diferente para criar a árvore de ports. Para adicionar uma árvore de ports adicional para testar modificações locais e para o desenvolvimento de ports, é possível baixar a árvore via <application>Subversion</application>:</para> + + <screen><prompt>#</prompt> <userinput>poudriere ports -c -m svn+https -p subversive</userinput></screen> + + <note> + <para>Os métodos <acronym>http</acronym> e <acronym>https</acronym> precisam que o <package role="port">devel/subversion</package> seja compilado com a opção <literal>SERF</literal> ativada. Ela vem habilitada por padrão.</para> + </note> + + <para>Cria <literal>tank/poudriere/ports/subversive</literal> e o monta em <filename>/poudriere/ports/subversive</filename>. Em seguida, ele é povoado usando <application>Subversion</application>. Finalmente, ele é adicionado à lista de árvores de ports conhecidas:</para> + + <screen><prompt>#</prompt> <userinput>poudriere ports -l</userinput> +PORTSTREE METHOD PATH +default portsnap /poudriere/ports/default +subversive svn+https /poudriere/ports/subversive</screen> + + <tip> + <para>O método <literal>svn</literal> permite qualificadores extras para dizer ao <application>Subversion</application> exatamente como buscar os dados. Isso é explicado em <citerefentry vendor="ports"><refentrytitle>poudriere</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Por exemplo, <command>poudriere ports -c -m svn+ssh -p subversive</command> usa o <application>SSH</application> para o checkout.</para> + </tip> + + </sect2> + + <sect2 xml:id="testing-poudriere-ports-tree-manual"> + <title>Usando Árvores de Ports Gerenciadas Manualmente com o Poudriere</title> + + <para>Dependendo do fluxo de trabalho, pode ser extremamente útil usar árvores de ports que são mantidas manualmente. Por exemplo, se houver uma cópia local da árvore de ports em <filename>/work/ports</filename>, aponte o <application>Poudriere</application> para o local:</para> + + <screen><prompt>#</prompt> <userinput>poudriere ports -c -F -f none -M /work/ports -p development</userinput></screen> + + <para>Isto será listado na tabela de árvores conhecidas:</para> + + <screen><prompt>#</prompt> <userinput>poudriere ports -l</userinput> +PORTSTREE METHOD PATH +development - /work/ports</screen> + + <note> + <para>O traço na coluna <literal>METHOD</literal> significa que o <application>Poudriere</application> nunca irá atualizar ou alterar esta árvore de ports. É de responsabilidade total do usuário a manutenção desta árvore, incluindo todas as modificações locais que podem ser usadas para testar novos ports e enviar patches.</para> + </note> + + </sect2> + + <sect2 xml:id="testing-poudriere-ports-tree-updating"> + <title>Mantendo as Árvores de Ports do Poudriere Atualizadas</title> + + <para>Tão simples quanto com as jails descritas anteriormente:</para> + + <screen><prompt>#</prompt> <userinput>poudriere ports -u -p <replaceable>PORTSTREE</replaceable></userinput></screen> + + <para>Vai atualizar a <replaceable>PORTSTREE</replaceable>, uma árvore dada pela saída de <command>poudriere -l</command>, para a última revisão disponível nos servidores oficiais.</para> + + <note> + <para>As arvores de ports sem um método, veja <xref linkend="testing-poudriere-ports-tree-manual"/>, não podem ser atualizadas assim. Elas devem ser atualizadas manualmente pelo mantenedor de ports.</para> + </note> + + </sect2> + + <sect2 xml:id="testing-poudriere-testing-ports"> + <title>Testando Ports</title> + + <para>Depois que as jails e as árvores de ports foram configuradas, o resultado das modificações de um colaborador na árvore de ports pode ser testado.</para> + + <para>Por exemplo, modificações locais no port <package role="port">www/firefox</package> localizado em <filename>/work/ports/www/firefox</filename> pode ser testado na jail 11.1-RELEASE criada anteriormente:</para> + + <screen><prompt>#</prompt> <userinput>poudriere testport -j 111Ramd64 -p development -o www/firefox</userinput></screen> + + <para>Isso irá compilar todas as dependências do <application>firefox</application>. Se uma dependência foi criada anteriormente e ainda está atualizada, o pacote pré-criado é instalado. Se uma dependência não tiver um pacote atualizado, ela será compilada com opções padrão em uma jail. Depois disso o <application>firefox</application> será compilado.</para> + + <para>A compilação completa de cada port será registrada em <filename>/poudriere/data/logs/bulk/111Ri386-development/<replaceable>build-time</replaceable>/logs</filename>.</para> + + <para>O nome do diretório <literal>111Ri386-development</literal> é derivado dos argumentos para <literal>-j</literal> e <literal>-p</literal>, respectivamente. Por conveniência, um link simbólico <filename>/poudriere/data/logs/bulk/111Ri386-development/latest</filename> também é mantido. O link aponta para o mais recente diretório <replaceable>build-time</replaceable>. Neste diretório também se encontra um <filename>index.html</filename> para que possa ser possível observar o processo de compilação com um navegador web.</para> + + <para>Por padrão, o <application>Poudriere</application> limpa as jails e deixa os arquivos de log nos diretórios mencionados acima. Para facilitar a investigação, as jails podem ser mantidas em execução após a compilação, adicionando a opção <option>-i</option> ao <command>testport</command>:</para> + + <screen><prompt>#</prompt> <userinput>poudriere testport -j 111Ramd64 -p development -i -o www/firefox</userinput></screen> + + <para>Depois que a compilação é concluída, e independentemente de ter sido bem-sucedida, um shell é fornecido dentro da jail. O shell é usado para investigações adicionais. O <application>Poudriere</application> pode ser dito para deixar a jail em execução após a conclusão da compilação com <option>-i</option>. O <application>Poudriere</application> mostrará o comando para ser executado quando a jail não for mais necessária. E então é possível fazer um <citerefentry><refentrytitle>jexec</refentrytitle><manvolnum>8</manvolnum></citerefentry> para dentro dele:</para> + + <screen><prompt>#</prompt> <userinput>poudriere testport -j 111Ramd64 -p development -I -o www/firefox</userinput> +[...] +====>> Installing local Pkg repository to /usr/local/etc/pkg/repos +====>> Leaving jail 111Ramd64-development-n running, mounted at /poudriere/data/.m/111Ramd64-development/ref for interactive run testing +====>> To enter jail: jexec 111Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root +====>> To stop jail: poudriere jail -k -j 111Ramd64 -p development +<prompt>#</prompt> <userinput>jexec 111Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root</userinput> +<prompt>#</prompt> <userinput><replaceable>[do some stuff in the jail]</replaceable></userinput> +<prompt>#</prompt> <userinput>exit</userinput> +<prompt>#</prompt> <userinput>poudriere jail -k -j 111Ramd64 -p development</userinput> +====>> Umounting file systems</screen> + + <para>Uma parte integral da infraestrutura de compilação de ports do FreeBSD é a capacidade de ajustar os ports as preferências pessoais por meio de opções. Elas podem ser testadas com o <application>Poudriere</application> também. Adicionando a opção <option>-c</option>:</para> + + <screen><prompt>#</prompt> <userinput>poudriere testport -c -o www/firefox</userinput></screen> + + <para>Apresenta o diálogo de configuração do port antes que o port seja compilado. Os ports informados após o <option>-o</option> no formato <literal><replaceable>category</replaceable>/<replaceable>portname</replaceable></literal> usará as opções especificadas, todas as dependências usarão as opções padrão. O teste de ports dependentes com opções não padrão pode ser realizado usando conjuntos, consulte <xref linkend="testing-poudriere-sets"/>.</para> + + <tip> + <para>Ao testar ports nos quais o <filename>pkg-plist</filename> é alterado durante a compilação, dependendo das opções selecionadas, é recomendável executar um teste com todas as opções selecionadas <emphasis>e</emphasis> um com todas as opções desmarcadas.</para> + </tip> + </sect2> + + <sect2 xml:id="testing-poudriere-sets"> + <title>Usando Conjuntos</title> + + <para>Para todas as ações envolvendo builds, um então chamado <emphasis>conjunto</emphasis> pode ser especificado usando <literal>-z <replaceable>setname</replaceable></literal>. Um conjunto se refere a uma compilação totalmente independente. Isso permite, por exemplo, o uso de <command>testport</command> com opções não padrão para os ports dependentes.</para> + + <para>Para usar sets, o <application>Poudriere</application> espera uma estrutura de diretórios existente semelhante a <varname>PORT_DBDIR</varname>, o padrão é <filename>/var/db/ports</filename> no seu diretório de configuração. Este diretório é então <citerefentry><refentrytitle>nullfs</refentrytitle><manvolnum>5</manvolnum></citerefentry>-montado nas jails onde os ports e suas dependências são compilados. Normalmente, um ponto de partida adequado pode ser obtido copiando de forma recursiva o <varname>PORT_DBDIR</varname> para <filename>/usr/local/etc/poudriere.d/<replaceable>jailname</replaceable>-<replaceable>portname</replaceable>-<replaceable>setname</replaceable>-options</filename>. Isso é descrito em detalhes em <citerefentry vendor="ports"><refentrytitle>poudriere</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Por exemplo, para testar o <package role="port">www/firefox</package> em um conjunto específico chamado <literal>devset</literal>, adicione o parâmetro <literal>-z devset</literal> ao comando testport:</para> + + <screen><prompt>#</prompt> <userinput>poudriere testport -j 111Ramd64 -p development -z devset -o www/firefox</userinput></screen> + + <para>Isso irá procurar pela existência desses diretórios nesta ordem:</para> + + <itemizedlist> + <listitem> + <para><filename>/usr/local/etc/poudriere.d/111Ramd64-development-devset-options</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/111Ramd64-devset-options</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/111Ramd64-development-options</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/devset-options</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/development-options</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/111Ramd64-options</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/options</filename></para> + </listitem> + </itemizedlist> + + <para>Desta lista, o <application>Poudriere</application> <citerefentry><refentrytitle>nullfs</refentrytitle><manvolnum>5</manvolnum></citerefentry>-monta a <emphasis>primeira árvore existente</emphasis> de diretório para o diretório <filename>/var/db/ports</filename> das jails de compilação. Portanto, todas as opções personalizadas são usadas para todos os ports durante essa execução do <command>testport</command>.</para> + + <para>Depois que a estrutura de diretório para um conjunto é fornecida, as opções para um port específico podem ser alteradas. Por exemplo:</para> + + <screen><prompt>#</prompt> <userinput>poudriere options -c www/firefox -z devset</userinput></screen> + + <para>O diálogo de configuração para o <package role="port">www/firefox</package> é mostrado e as opções podem ser editadas. As opções selecionadas são salvas no set <literal>devset</literal>.</para> + + <note> + <para><application>Poudriere</application> é muito flexível na configuração das opções. Elas podem ser configuradas para jails específicas, árvores de ports e para vários ports por um comando. Veja <citerefentry vendor="ports"><refentrytitle>poudriere</refentrytitle><manvolnum>8</manvolnum></citerefentry> para detalhes.</para> + </note> + + </sect2> + + <sect2 xml:id="testing-poudriere-make-conf"> + <title>Fornecendo um Arquivo <filename>make.conf</filename> Customizado</title> + + <para>Semelhante ao uso de conjuntos (sets), o <application>Poudriere</application> também usará um <filename>make.conf</filename> personalizado se for fornecido. Nenhum argumento de linha de comando especial é necessário. Em vez disso, o <application>Poudriere</application> procura por arquivos existentes que correspondam a um esquema de nomes derivado da linha de comando. Por exemplo:</para> + + <screen><prompt>#</prompt> <userinput>poudriere testport -j 111Ramd64 -p development -z devset -o www/firefox</userinput></screen> + + <para>faz o <application>Poudriere</application> verificar a existência desses arquivos nesta ordem:</para> + + <itemizedlist> + <listitem> + <para><filename>/usr/local/etc/poudriere.d/make.conf</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/devset-make.conf</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/development-make.conf</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/111Ramd64-make.conf</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/111Ramd64-development-make.conf</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/111Ramd64-devset-make.conf</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/poudriere.d/111Ramd64-development-devset-make.conf</filename></para> + </listitem> + </itemizedlist> + + <para>Ao contrário dos conjuntos, todos os arquivos encontrados serão anexados, <emphasis>naquela ordem</emphasis>, em um <filename>make.conf</filename> dentro das jails de compilação. Assim, é possível ter variáveis gerais, destinadas a afetar todas as compilações <filename>/usr/local/etc/poudriere.d/make.conf</filename>. Variáveis especiais, destinadas a afetar apenas determinadas jails ou conjuntos, podem ser setadas em arquivos especiais como <filename>make.conf</filename>, assim como <filename>/usr/local/etc/poudriere.d/111Ramd64-development-devset-make.conf</filename>.</para> + + <example xml:id="testing-poudriere-sets-perl"> + <title>Usando <filename>make.conf</filename> para Alterar o <application>Perl</application> Padrão</title> + + <para>Para compilar um conjunto com uma versão não padrão do <application>Perl</application>, por exemplo, <literal>5.20</literal>, usando um conjunto chamado <literal>perl5-20</literal>, crie um <filename>perl5-20-make.conf</filename> com esta entrada:</para> + + <programlisting>DEFAULT_VERSIONS+= perl=5.20</programlisting> + + <note> + <para>Observe o uso de <literal>+=</literal> de modo que, se a variável já estiver definida no <filename>make.conf</filename> padrão, seu conteúdo não será sobrescrito.</para> + </note> + </example> + + </sect2> + + <sect2 xml:id="testing-poudriere-pruning-distfiles"> + <title>Remoção de Distfiles Não Mais Necessários</title> + + <para><application>Poudriere</application> vem com um mecanismo embutido para remover distfiles desatualizados que não são mais usados por qualquer port de uma determinada árvore. O comando</para> + + <screen><prompt>#</prompt> <userinput>poudriere distclean -p <replaceable>portstree</replaceable></userinput></screen> + + <para>irá escanear a pasta distfiles, <varname>DISTFILES_CACHE</varname> dentro do <filename>poudriere.conf</filename>, contra a á |