path: root/pt_BR.ISO8859-1/books/porters-handbook/book.xml

<?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> <year>2019</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 &gt;&gt; /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 &lt;bsd.port.mk&gt;</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 stage-qa</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