git-svn-id: svn+slack://slack.fluxo.info/var/svn/simplepkg@484 04377dda-e619-0410-9926-eae83683ac58

1 files changed, 178 insertions, 22 deletions

diff --git a/trunk/doc/mkbuild-pt_BR.tex b/trunk/doc/mkbuild-pt_BR.tex
index d0516d6..33de6fc 100644
--- a/trunk/doc/mkbuild-pt_BR.tex
+++ b/trunk/doc/mkbuild-pt_BR.tex
@@ -35,7 +35,7 @@
 
 \title{Construindo SlackBuilds com mkbuild}
 
-\author{Rudson Alves}
+\author{Rudson Alves\\v. 1.2}
 
 \date{\today}
 
@@ -62,7 +62,7 @@ O \textit{mkbuild} utiliza o modelo padrão \textit{generic.mkSlackBuild}, armaze
 /etc/simplepkg/defaults/mkbuild/
 \end{verbatim}
 
-Este modelo é uma versão setorizada do \textit{generic.SlackBuild}, levemente modificada. O \textit{generic.SlackBuild} é um modelo genérico de \textit{Slackbuilds} disponibilizado na árvore de \textit{Slackbuilds} do \textit{Slack.Sarava}, para servir como modelo para a construção dos \textit{scripts}. Outros modelos setorizados podem ser utilizados pelo \textit{mkbuild}, a única limitação é quanto ao nome da seção \textit{slackdesc}, que não poderá ser alterada.
+Este modelo é uma versão setorizada do \textit{generic.SlackBuild}, levemente modificada. O \textit{generic.SlackBuild} é um modelo genérico de \textit{Slackbuilds} criado por nosso colega e colaborador Luis, para servir como modelo para a construção dos \textit{Slackbuilds}. Outros modelos setorizados podem ser utilizados pelo \textit{mkbuild}, a única limitação é quanto ao nome da seção \textit{slackdesc}, que não poderá ser alterada.
 
 
 \subsection{Os Campos}
@@ -122,7 +122,7 @@ REST OF DOINST.SH          & conteúdo do doinst.sh                   \\
 \end{tabular}
 \\\\
 
-Em alguns casos o nome do pacote difere do nome da fonte, como é o caso da fonte \textit{sigc++}, que gera o pacote de nome \textit{libsiggc++}. Por este motivo que existem os campos \textit{SOURCE NAME} e \textit{PACKAGE NAME}. Para uma compreensão mais profunda destes campos, aconselho fazer uma análise mais rofunda do \textit{script} \textit{generic.SlackBuild}.
+Em alguns casos o nome do pacote difere do nome da fonte, como é o caso da fonte \textit{sigc++}, que gera o pacote de nome \textit{libsiggc++}. Por este motivo que existem os campos \textit{SOURCE NAME} e \textit{PACKAGE NAME}. Para uma compreensão mais profunda destes campos, aconselho fazer uma análise mais detalhada do modelo \textit{generic.mkSlackBuild}.
 
 
 \subsection{As Seções}
@@ -174,15 +174,23 @@ clean\_builds                & remove fontes e instalação temporária    & off &
 \end{tabular}
 \\\\
 
-A terceira e a quarta colunas da tebela acima apresentam o status padrão para as seções nas versões 1.0.x e 1.1.x do \textit{mkbuild}. No \textit{mkbuild} versão 1.0.x, as seções \textbf{all} são configuradas no modelo \textit{generic.mkSlackBuild}. A partir da versão 1.1.x estas seções serão definidas como \textbf{on} ou \textbf{all} no \textit{model.mkbuild}, não mais no \textit{generic.mkSlackBuild}.
+A terceira e a quarta colunas da tebela acima apresentam o status padrão para as seções nas versões 1.0.x e 1.1.x do \textit{mkbuild}. No \textit{mkbuild} versão 1.0.x, as seções \textbf{all} são configuradas no modelo \textit{generic.mkSlackBuild}. A partir da versão 1.1.x estas seções serão definidas como \textbf{on} ou \textbf{off} no \textit{model.mkbuild}, não mais no modelo \textit{generic.mkSlackBuild}.
 
 
 \section{Configuração}
 
-Por hora, o \textit{mkbuild} utiliza apenas um variável de configuração em /etc/simplepkg/simplepkg.conf. A variável \textit{SLACKBUILDS\_DIR} é necessária para utilizar o \textit{mkbuild} com a opção "\verb!-c!" ou "\verb!--commit!", que incorpora os arquivos \textit{SlackBuild} e \textit{slack-required} à estrutura de diretórios do \textit{Slack.Sarava}, na cópia local.
+O \textit{mkbuild} utiliza quatro variáveis de configuração em /etc/simplepkg/simplepkg.conf. São elas:
 
+\begin{description}
+ \item[SLACKBUILDS\_DIR] diretório onde serão guardados os \textit{SlackBuilds} e \textit{slack-required} gerados. Necessário para o uso com a opção \textbf{-c}, \textit{commit}. Padrão /var/simplaret/slackbuilds;
+ \item[MKBUILDS\_DIR] diretório onde serão guardados os \textit{.mkbuilds} criados. Necessário para o uso com a opção \textbf{-c}, \textit{commit}. Padrão /var/simplaret/mkbuilds;
+ \item[SLACKBUILDS\_SVN] endereço do repositório subversion dos \textit{SlackBuilds}. Mantenha o valor padrão;
+ \item[MKBUILDS\_SVN] endereço do repositório subversion dos \textit{SlackBuilds}. Mantenha o valor padrão;
+ \item[COLOR_MODE] define modo de cores para o \textit{mkbuild} e \textit{createpkg}. Padrão \textit{none}, preto e branco.
+ \end{description}
 
-\section{Criando o SlackBuild de um aplicativo}
+
+\section{Criando o SlackBuild do aplicativo pyrex}
 
 Para fazer um \textit{SlackBuild} com o \textit{mkbuild} é necessário criar um arquivo com os parâmetros que deseja que sejam passados para o modelo. Um arquivo de configuração simples, \textit{sample-Pyrex-small.mkbuild}, é apresentado abaixo:
 
@@ -265,13 +273,13 @@ Embora existam muitos parâmetros no modelo \textit{generic.mkSlackBuild}, nem to
 
 O mkbuild remove o nome do pacote, versão, assinatura do autor e várias outras informações destes dados, seguindo alguns critérios descritos a seguir.
 
-A sintaxe para a passagem de parâmetros ao \textit{mkbuild} é
+A sintaxe para a passagem de parâmetros ao \textit{mkbuild} pelo arquivo de parâmetros \textit{.mkbuild} é
 
 \begin{verbatim}
 [[DESCRIÇÃO DO PARÂMETRO]]="Parâmetro entre aspas duplas"
 \end{verbatim}
 
-As aspas duplas podem ser omitidas\footnote{Nas versões inferiores a 0.9.9, do \textit{mkbuild}, o aspas duplo é o delimitador e por isto é obrigatório. Um parâmetro passado sem o aspas duplo será interpretado como um parâmetro vazio, nestas versões.}. O delimitador utilizado pelo \textit{mkbuild} é o primeiro caracter igual (=) a aparecer na linha. Qualquer outra ocorrência de caracter igual será lido como parte do parâmetro. O mesmo acontece com comentários colocados após o caracter igual. Por exemplo, na linha abaixo:
+As aspas duplas podem ser omitidas\footnote{Nas versões inferiores a 0.9.9, do \textit{mkbuild}, a aspas dupla é o delimitador e por isto é obrigatório. Um parâmetro passado sem o aspas duplo será interpretado como um parâmetro vazio, nestas versões.}. O delimitador utilizado pelo \textit{mkbuild} é o primeiro caracter igual (=) a aparecer na linha e o fim de linha. Qualquer outra ocorrência de caracter igual será lido como parte do parâmetro. O mesmo acontece com comentários colocados após o caracter igual. Por exemplo, na linha abaixo:
 
 \begin{verbatim}
 [[PARÂMETRO TEST]]=Este parâmetro é um teste            # Este comentário será lido.
@@ -550,9 +558,9 @@ off: postinstall_script
 No caso do exemplo acima, são desabilitadas as seções: \textit{md5sum\_download\_and\_check\_0}, \textit{md5sum\_download\_and\_check\_1}, \textit{gpg\_signature\_check}, \textit{patch\_source}, \textit{compress\_manpages}, \textit{compress\_info\_files} e \textit{postinstall\_script}. Linhas iniciadas por uma tralha, \#, são ignoradas. Como no modelo generic.mkSlackBuild todas as seções estão desabilitadas ("off"), apenas as seções ligadas necessitam ser habilitadas.
 
 
-\subsubsection{Substituição de seções do modelo}
+\subsection{Substituição de seções no modelo}
 
-Em algumas situações pode ser necessário substituir o conteúdo de uma seção. Estas mudanças nas seções são feitas por iniciar uma seção, no arquivo de parâmetros, por "\verb!#>nome_da_seção!" e terminar por "\verb!#<nome_da_seção!". Quando o \textit{mkbuild} localiza estas seções no arquivo de parâmetros, ele substitui as seções padrões, de mesmo nome, pelo conteúdo definido no arquivo de parâmetros. Por exemplo:
+Em algumas situações pode ser necessário substituir o conteúdo de uma seção. Estas mudanças são feitas iniciando uma seção, no arquivo de parâmetros, pela \textit{tag} "\verb!#>nome_da_seção!" e terminar pela \textit{tag} "\verb!#<nome_da_seção!". Quando o \textit{mkbuild} localiza estas seções no arquivo de parâmetros, ele substitui as seções padrões, de mesmo nome, pelo conteúdo definido no arquivo de parâmetros. Por exemplo:
 
 \begin{verbatim}
 #>untar_source
@@ -590,19 +598,149 @@ pyrex:
 Para esta seção, o \textit{mkbuild} irá substituir o parâmetro \textit{[[SLACK-DESC]]} pelo conteúdo definido entre "\verb!#>slackdesc!" e "\verb!#<slackdesc!", além de redimensionar a régua de orientação do \textit{slack-desc}.
 
 
-\section{Considerações Finais}
+\section{Exemplo 2: mkbuild do dosbox}
+
+Embora a documentação do comando \textit{mkbuild} seja relativamente longa, não é necessário muito esforço para se fazer um \textit{SlackBuild} de um \textit{pacote bem comportado}.
+
+Entenda-se por \textit{pacote bem comportado}, pacotes que podem ser construídos pelos comandos: 
+
+\begin{verbatim}
+ # ./configure && make && make install
+\end{verbatim}
+
+\nodeps e cujo o nome da fonte obedeça o padrão: \textit{NOME.DO.PACOTE-VERSÃO.tar.EXTENSÃO}}. Um bom exemplo disto é o pacote do dosbox, o qual será usado como exemplo nesta seção.
+
+Inicie a construção do \textit{.mkbuild} com o comando abaixo:
+
+\begin{verbatim}
+# mkbuild -a "<<seu nome>>" -ai "<<iniciais>>" -n dosbox
+\end{verbatim}
+
+Não é necessário o nome e assinatura passados pelas opções \textbf{-a} e \textbf{-ai}, mas é aconselhável. A opção \textbf{-n} diz ao \textit{mkbuild} para copiar o modelo em \textit{/etc/simplepkg/\dots/model.mkbuild}, para o diretório atual com o nome \textit{dosbox.mkbuild}, e aplicar o nome "dosbox" a este modelo.
+
+Em seguida, edite o arquivo \textit{dosbox.mkbuild}, com um editor de sua escolha, e preencha os campos com os valores abaixo:
+
+\begin{verbatim}
+[[DOWNLOAD FOLDER URL]]="http://downloads.sourceforge.net/dosbox/dosbox-0.71.tar.gz"
+[[SLACKBUILD PATH]]="games/emulation/dosbox"
+
+#>slackdesc
+dosbox: DOSBox.slackBuild by Slack.Sarava
+dosbox:
+dosbox: DOSBox is a DOS-emulator that uses the SDL-library which makes DOSBox
+dosbox: very easy to port to different platforms. DOSBox has already been 
+dosbox: ported to many different platforms, such as Windows, BeOS, Linux, 
+dosbox: MacOS X...
+dosbox:
+dosbox: DOSBox also emulates CPU:286/386 realmode/protected mode, Directory 
+dosbox: FileSystem/XMS/EMS, Tandy/Hercules/CGA/EGA/VGA/VESA graphics, a 
+dosbox: SoundBlaster/Gravis Ultra Sound card for excellent sound 
+dosbox: compatibility with older games...
+#<slackdesc
+
+\end{verbatim}
+
+Por se tratar de um \textit{pacote bem comportado}, o \textit{dosbox.mkbuild} é bem simples. Todas as informações são removidas da URL do programa, não necessitando de mais declarações. O campo \textit{SLACKBUILD PATH} é necessário apenas se você for enviar o \textit{SlackBuild} para o repositório do grupo \textit{Slack.Sarava}. A seção \textit{slackdesc} também não é necessária, mas é importante, pois informa o conteúdo do pacote durante a instalação.
+
+
+\section{Criando um \textit{patch} para pequenas alterações}
+
+A partir da versão 1.2 do \textit{mkbuild} é possível fazer pequenas alterações ao modelo \textit{generic.mkSlackBuild}, com a aplicação de um \textit{patch} simplificado. Este \textit{patch} é aplicado ao modelo \textit{generic.mkSlackBuild} antes que qualquer outra edição seja feita ao modelo.
+
+Um \textit{patch} simplificado deve ser definido no arquivo de parâmetros \textit{.mkbuild} entre as \textit{tags} \verb!#p>! e \verb!#p<!, com no exemplo abaixo:
+
+\begin{verbatim}
+...
+#p>
+... Alterações ...
+#p<
+...
+\end{verbatim}
+
+As linhas com as alterações devem sempre iniciar com um \textit{caracter de controle}, seguido pelo conteúdo da linha a ser alterada, removida ou conferida ao modelo \textit{generic.mkSlackBuild}. O formato do \textit{patch} usado pelo \textit{mkbuild} segue o mesmo padrão gerado pelo comando \verb!diff -u!, com as seguintes diferenças:
+
+\begin{enumerate}
+ \item Não possui numeração de linhas. A posição das alterações é referenciada por uma ou mais linhas de referência. Uma linha de referência deve ser única, ou em caso de várias linhas, a seqüência deve ser única;
+ \item O número de linhas de referência é variável e não necessita de linhas de referência ao final da alteração;
+ \item O caracter para separar as alterações é o caracter igual, =.
+\end{enumerate}
+
+
+\subsection{Caracteres de controle}
+
+Os \textit{caracteres de controle} são apenas quatro. Com eles é possível fazer todas as alterações por substituição de linha necessárias em um \textit{patch}. Segue abaixo a descrição destes caracteres de controle:
+
+\begin{description}
+ \item[" " (espaço)] este caracter de controle serve para definir linhas de referência, necessárias para localizar a posição das alterações no modelo \textit{generic.mkSlackBuild};
+ \item[- (menos)] serve para referenciar linhas que serão removidas do modelo. Este caracter de controle serve ainda para definir linhas de referência, entretanto lembre-se que elas serão removidas;
+ \item[+ (mais)] serve para indicar linhas que serão adicionadas ao modelo, logo após a referência;
+ \item[= (igual)] serve para indicar o final de uma alteração e iniciar a próxima. Qualquer coisa colocado após um \textit{caracter de controle} igual, será ignorado.
+ \end{description}
+
+Para simplificar a compreensão do funcionamento deste \textit{patch} simplificado, segue abaixo um exemplo para alterações hipotéticas.
+
+
+\subsection{mkpatch: Alterando uma linha}
+
+Neste exemplo, será alterado o conteúdo da variável \textit{ARCH} para fixá-la em \textit{i586}. Isto pode ocorre na construção de pacotes de programas pré-compilados ou um pacote binário. Para fazer esta alteração, basta acrescentar o \textit{patch} abaixo ao final do arquivo \textit{.mkbuild}:
+
+\begin{verbatim}
+...
+#p>
+ PKG_NAME="[[PACKAGE NAME]]"
+-ARCH=${ARCH:=[[ARCH]]}
++ARCH=i586
+#p<
+\end{verbatim}
+
+A primeira linha, \verb!PKG_NAME="[[PACKAGE NAME]]"!, iniciada pelo \textit{caracter de controle} \textbf{espaço}, é uma linha de referência a ser procurada no modelo \textit{generic.mkSlackBuild}, posicionando a alteração ao modelo. A segunda linha, com o \textit{caracter de controle} \textbf{menos}, indica a linha que será removida: \verb!ARCH=${ARCH:=[[ARCH]]}"!. A terceira linha, com o \textit{caracter de controle} \textbf{mais}, será adicionada logo em seguida: \verb!ARCH=i586!.
+
+Observe que o mesmo poderia ser feito com o \textit{patch} abaixo:
+
+\begin{verbatim}
+...
+#p>
+-ARCH=${ARCH:=[[ARCH]]}
++ARCH=i586
+#p<
+\end{verbatim}
+
+Como o \textit{caracter de controle} \textbf{menos} também serve como referência e a alteração será feita da mesma forma.
+
+
+\subsection{mkpatch: Aplicando uma segunda alteração}
+
+Para uma segunda alteração ao modelo, vou alterar a forma de instalação e fazer mais algumas edições a seção \textit{strip_binaries}:
+
+\begin{verbatim}
+#p>
+-ARCH=${ARCH:=[[ARCH]]}
++ARCH=i586
+===
+ <install_package> off
+-# Install
++# Install Setup
+-make install DESTDIR="$PKG" || exit $ERROR_INSTALL
+-./setup --prefix="$PKG" || exit $ERROR_INSTALL
+===
+ # Strip binaries
+ ( cd "$PKG"
+-  find . | xargs file | grep "executable" | grep ELF | cut -f 1 -d : | \
+-    xargs strip --strip-unneeded 2> /dev/null
+-  find . | xargs file | grep "shared object" | grep ELF | cut -f 1 -d : | \
+-    xargs strip --strip-unneeded 2> /dev/null
++  find . | xargs file | grep ELF | xargs strip --strip-unneeded 2> /dev/null
+#p<
+\end{verbatim}
+
+A segunda alteração, troca a linha de comentário adicionado a palavra \verb!Setup! e por fim o comando de instalação, para a chamada \verb!./setup! \dots
+
+A terceira alteração é feita à seção \textit{strip_binaries}, onde os dois comando \verb!find! são trocados por um terceiro mais simples.
 
-Para simplificar a construção dos \textit{SlackBuilds} é aconselhável editar o arquivo \verb!/etc/simplepkg/defaults/mkbuild/model.mkbuild! e adicionar algumas declarações padrões como:
 
-\begin{itemize}
-\item \textit{SLACKBUILD AUTHOR} - com o seu nome
-\item \textit{SLACKBUILD AUTHOR INITIALS} - a assinatura dos pacotes
-\item \textit{SLACKBUILD MODEL} - caso o modelo utilizado difira do modelo padrão
-\item \textit{NUMBER OF JOBS} - com o valor desejado
-\item \dots
-\end{itemize}
+\section{Apêndice-A}
 
-Vários destes parâmetros também podem ser passados ao \textit{mkbuild} pela linha de comando. Um manual completo destas opções pode ser consultado passando flag \verb!-h!, ao \textit{mkbuild}:
+Vários outros parâmetros podem ser passados ao \textit{mkbuild} pela linha de comando. Um manual completo destas opções pode ser consultado passando \textit{flag} \verb!--help! ou \verb!-h!, ao \textit{mkbuild}:
 
 \begin{verbatim}
 NAME
@@ -619,6 +757,8 @@ DESCRIPTION
                 author name
             -ai, --author_initials <initials>
                 author signature
+            -bn, --build-number
+                change build number
             -cs, --const_string <string>
                 construction string to source name
             -u, --url <url_address>
@@ -635,20 +775,36 @@ DESCRIPTION
                 Number of jobs to run simultaneously
             --prefix <install_dir>
                 Prefix install directory
+            -pf, --patch-files
+                List of patch files
+            -npss, --nps-strip
+                Number of prefix slashes to strip
 
         Program options:
         -h, --help
             this help mesage
-        -c, --commit
-            commit SlackBuilds in local svn tree
+        -cs, --commit-slackbuild
+            commit SlackBuilds in local svn SlackBuild tree
+        -cm, --commit-mkbuild
+            commit .mkbuild in local svn mkbuild tree
+        -c, --commit-all
+            commit SlackBuild and .mkbuild files in local svn tree
         -n, --new <mkbuild_name>
             start a new mkbuild configure file
         -v, --version
             program version
         -V, --verbose
             print debug information
+        -sp, --slackbuild-path
+            print SlackBuild path in Slack.Sarava tree
 
 EXAMPLES
+        mkbuild -c pyrex.mkbuild
+            build pyrex.SlackBuild and commit .mkbuild and .SlackBuild in
+            Slack.Sarava local tree.
+        mkbuild -a "Jose Araujo" -ai "ja" -n pyrex
+            make a basic pyrex.mkbuild with author name "Jose Araujo" and
+            author signature "ja".
         mkbuild --prefix /usr/local pyrex.mkbuild
             build pyrex.SlackBuild with prefix /usr/local and pyrex.mkbuild
             variables and options definitions.