path: root/trunk/doc/mkbuild-pt_BR.tex

\documentclass[12pt,a4paper,oneside]{article}
%\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage[dvips]{graphicx}
%\usepackage{subfigure}
\usepackage{mdwlist}
\usepackage{a4}
%\topmargin -.5in
%\addtolength{\hoffset}{-1.0cm}
%\addtolength{\textwidth}{3.0cm}
%\textwidth = 400pt
%\textheight = 680pt

\makeatletter

%\usepackage[pdftex]{color,graphicx}
%\DeclareGraphicsExtensions{.jpg,.pdf,.mps,.png}

\usepackage[brazil]{babel}
\usepackage[dvips]{graphicx}
%\usepackage{textdraw}

\input texdraw
%\newenvironment{textdraw}{\leavevmode\btexdraw}{\etexdraw}

\newcommand{\rcap}[1]{Cap�tulo \ref{#1}}
\newcommand{\rfig}[1]{Figura \ref{#1}}
\newcommand{\rtab}[1]{Tabela \ref{#1}}
\newcommand{\rsec}[1]{Se��o \ref{#1}}

\makeatother

\begin{document}


\title{Construindo SlackBuilds com mkbuild}

\author{Rudson Alves\\v. 1.2}

\date{\today}

\maketitle

%\pagenumbering{roman}

\tableofcontents{}
%\listoffigures
%\listoftables

%\abstract{...}


\section*{Introdu��o}

O \textit{mkbuild} � um programa em \textit{script shell} que auxiliar na constru��o de pacotes para o \textit{Slackware}. A grosso modo, o \textit{mkbuild} � um construtor de \textit{Slackbuild}\footnote{\textit{SlackBuilds} s�o \textit{script} utilizado para a constru��o de um pacote bin�rio de um programa, no \textit{Slackware}.}. Ele opera a partir de um arquivo de par�metros e de modelos de \textit{Slackbuilds} parametrizados.

Este texto apresenta informa��es �teis para utiliza��o do \textit{mkbuild} na constru��o destes arquivos de par�metros, bem como configurar e utilizar modelos de \textit{SlackBuilds} e outras personaliza��es.

O \textit{mkbuild} � uma ferramenta distribu�da juntamente com o \textit{simplepkg}, um projeto do grupo Slack.Sarava. Para a utiliza��o desta ferramenta voc� dever� instalar o pacote conforme as instru��es abaixo:

\begin{verbatim}
# LASTVERSION=`lynx -dump http://slack.sarava.org/packages/noarch/ \
               | grep 'simplepkg-.*\.tgz' | awk '{print $2}'`
# wget $LASTVERSION
# installpkg simplepkg-*.tgz
\end{verbatim}

Para mais informa��es veja os links abaixo:

\begin{itemize}
 \item http://slack.sarava.org/simplepkg - Descri��o de todo o projeto \textit{Simplepkg}, por Rhatto - coordenador do projeto \textit{Slack.Sarava};
 \item http://slack.sarava.org/node/25 - Tutorial b�sico de instala��o do \textit{Simplepkg}, por rafael2k - um grande colaborador.
\end{itemize}


\section{O modelo generic.mkSlackBuild}

O \textit{mkbuild} utiliza o modelo padr�o \textit{generic.mkSlackBuild}, armazenado em

\begin{verbatim}
/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} criado por nosso colega e colaborador Lu�s, 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}

O modelo \textit{generic.mkSlackBuild} � um \textit{SlackBuild} gen�rico com v�rios campos destacados por duplo colchetes, [[ \dots ]], com mostra o trecho abaixo:

\begin{verbatim}
...
<set_variables> all
# Set variables
CWD="$(pwd)"
SRC_NAME="[[SOURCE NAME]]"
PKG_NAME="[[PACKAGE NAME]]"
ARCH=${ARCH:=[[ARCH]]}
SRC_VERSION=${VERSION:=[[VERSION]]}
PKG_VERSION="$(echo "$SRC_VERSION" | tr '[[:blank:]-]' '_')"
BUILD=${BUILD:=1[[SLACKBUILD AUTHOR INITIALS]]}
...
PREFIX=${PREFIX:=[[PREFIX]]}
PKG_SRC="$TMP/$SRC_NAME-$SRC_VERSION"
</set_variables>
...
\end{verbatim}

Uma breve descri��o destes campos � apresentada na tabela abaixo: \\
\\
\begin{tabular}{l|l}
\hline \hline
\textbf{Campo} & \textbf{Descri��o}\\
\hline \hline
PROGRAM NAME               & nome do programa                               \\
PROGRAM URL                & \textit{URL} da fonte do pacote                \\
SLACKBUILD AUTHOR          & nome do autor                                  \\
SOURCE NAME                & nome da fonte, sem vers�o ou extens�o          \\
PACKAGE NAME               & nome do pacote e ser gerado                    \\
ARCH                       & arquitetura do pacote. Padr�o i486      \\
VERSION                    & vers�o do pacote                               \\
SLACKBUILD AUTHOR INITIALS & assinatura utilizada pelo autor                \\
PREFIX                     & prefixo da instala��o (/usr, /opt, \dots)\\
SOURCE EXTENSION           & extens�o da fonte (bz2, gz, \dots) \\
UNPACKER                   & programa de dessempacotamento (geralmenrte "tar") \\
UNPACKER FLAGS             & flags para o desempacotador \\
DOWNLOAD FOLDER URL        & \textit{URL} da pasta onde se encontra a fonte \\
DECOMPRESSOR               & o descompressor para a fonte (gunzip, bunzip2, \dots) \\
DECOMPRESSOR TEST FLAG     & \textit{flag} de teste do descompressor        \\
SIGNING KEY URL            & \textit{URL} da chave \textit{gpg} do fonte    \\
SIGNING KEY                & chave \textit{gpg} da fonte                    \\
MD5SUM EXTENSION           & extens�o utilizada pelo arquivo \textit{md5sum}\\
PATCH FILES                & arquivo \textit{path}                          \\
NUMBER OF PREFIX SLASHES TO STRIP  & \dots                                  \\
SOURCE NAME CONSTRUCTION STRING  & string para a constru��o do nome do arquivo. O padr�o � \$SRC\_NAME-\$VERSION.tar.\$EXTENSION  \\
OTHER CONFIGURE ARGS       & argumentos de configura��o passados ao ./configure \\
DOCUMENTATION FILES        & lista de arquivos para a pasta /usr/doc/PACKAGE \\
SLACK-DESC                 & conte�do do slack-desc, descri��o do pacote \\
REST OF DOINST.SH          & conte�do do doinst.sh                   \\
\hline
\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 detalhada do modelo \textit{generic.mkSlackBuild}.


\subsection{As Se��es}

As se��es no modelo \textit{generic.mkSlackBuild}, s�o iniciadas pela \textit{tag} <nome\_da\_se��o> e terminadas com </nome\_da\_se��o>, como em um c�digo \textit{html}, \underline{sem espa�os}.

A �nica se��o que n�o pode ter seu nome alterado � \textit{slackdesc}. Esta se��o � editada de uma forma diferenciada pelo \textit{mkbuild} e a altera��o de seu nome poder� gerar erro.

Cada se��o possui uma \textit{flag} com os poss�veis valores:

\begin{description}
 \item[on] habilitado;
 \item[off] desabilitado;
 \item[all] sempre habilitado.
\end{description}

A inten��o destas \textit{flags} � gerar um padr�o para as se��es, deixando em \textbf{all} as se��es que dever�o estar sempre habilitadas e \textbf{on} ou \textbf{off} se��es que podem ser habilitadas ou desabilitadas de acordo com as necessidades do \textit{SlackBuild} que ser� constru�do\footnote{Na vers�o 1.1.x do mkbuild, todas as se��es foram configuradas como \textbf{off}, para simplificar a vizualiza��o do script de configura��o \textit{.mkbuild}.}.

As se��es padr�es do \textit{generic.mkSlackBuild} s�o listadas na tabela abaixo:
\\\\
\begin{tabular}{l|l|c|c}
\hline
Se��o & Descri��o & 1.0.x & 1.1.x\\
\hline
head                         & cabe�alho do \textit{SlackBuild}         & all & on \\
slackbuildrc                 & carrega \textit{script} \textit{slackbuildrc} & off & off \\
set\_variables               & inicia as vari�veis                      & all & on \\
slkflags                     & carrega \textit{flags} para compila��o   & all & on \\
error\_codes                 & c�digos de erro para o \textit{createpkg}  & off & off \\
start\_structure             & cria diret�rios para compila��o          & all & on \\
download\_source             & baixa a fonte do pacote                  & off & off \\
md5sum\_download\_and\_check\_0 & verifica \textit{md5sum} da fonte por c�digo & off & off \\
md5sum\_download\_and\_check\_1 & verifica \textit{md5sum} da fonte por arquivo & off & off \\
gpg\_signature\_check        & verifica assinatura \textit{gpg} da fonte & off & off \\
untar\_source                & desempacota a fonte                      & all & on \\
path\_source                 & aplica \textit{path} a fonte             & off & off \\
configure                    & configura pacote                         & off & off \\
make\_package                & compila o pacote                         & all & on \\
install\_package             & instala o pacote em diret�rio tempor�rio & all & on \\
strip\_binaries              & limpa bin�rios                           & off & off \\
compress\_manpages           & comprime p�ginas de manuais              & off & off \\
compress\_info\_files        & comprime arquivos \textit{info}          & off & off \\
install\_documentation       & instala documenta��o                     & off & off \\
slackdesc                    & \textit{slackdesc} do pacote             & off & off \\
postinstall\_script          & \textit{script} de p�s-instala��o        & off & off \\
build\_package               & constr�i pacote                          & all & on \\
clean\_builds                & remove fontes e instala��o tempor�ria    & off & off \\
\hline
\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{off} no \textit{model.mkbuild}, n�o mais no modelo \textit{generic.mkSlackBuild}.


\section{Configura��o}

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 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:

\begin{verbatim}
#--------------------
# Variables
#--------------------
# Author name
[[SLACKBUILD AUTHOR]]="Adalberto Sim�o Nader"

#
# Complete URL address or URL base address ( without $SRC_NAME-$VERSION... )
[[DOWNLOAD FOLDER URL]]="http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/Pyrex-0.9.5.1a.tar.gz"

#
# Default enable sections:
#      head, set_variables, slkflags, start_structure, untar_source,
#      make_package, install_package, build_package
# Warning: don't remove '#>>' and "#<<" tags.
#>> Start SlackBuild Sections:
 on: head
 on: slackbuildrc
 on: set_variables
 on: slkflags
 on: error_codes
 on: start_structure
 on: download_source
 on: md5sum_download_and_check_0
 on: untar_source
 on: configure
 on: make_package
 on: install_package
 on: strip_binaries
 on: install_documentation
 on: slackdesc
 on: build_package
 on: clean_builds
#<< End SlackBuild Sections

#------------------
# Sections changes
#------------------
#>slackdesc
pyrex: Pyrex by Slack.Sarava
pyrex:
pyrex: Pyrex is a language specially designed for writing Python extension
pyrex: modules. Its designed to bridge the gap between the nice, high-level,
pyrex: easy-to-use world of Python and the messy, low-level world of C.
pyrex:
pyrex:
pyrex:
pyrex:
pyrex:
pyrex:
#<slackdesc
\end{verbatim}

Isto � o suficiente para fazer o \textit{SlackBuild} do \textit{Pyrex}. Para construir o \textit{SlackBuild} basta chamar o \textit{mkbuild} passando este arquivo de par�metros:

\begin{verbatim}
$ mkbuild sample-Pyrex-small.mkbuild
$ ls
pyrex.SlackBuild      pyrex.mkbuild                sample-Pyrex-small.mkbuild
pyrex.SlackBuild.old  sample-Pyrex-large.mkbuild
\end{verbatim}

Ele ir� criar os arquivos \textit{pyrex.SlackBuild} e \textit{slack-required}, se o par�metro \textit{SLACK REQUIRED} for passado. Arquivos antigos ser�o renomeados para \textit{.old}.

Um modelo mais completo, com todos os par�metros, \textit{sample-Pyrex-large.mkbuild}, � disponibilizado junto com o \textit{mkbuild}. Nas se��es seguintes � apresentado uma breve descri��o dos par�metros e se��es deste arquivo de par�metros.


\subsection{Descri��o dos par�metros do arquivo \textit{.mkbuild}}

Embora existam muitos par�metros no modelo \textit{generic.mkSlackBuild}, nem todos s�o necess�rios para a constru��o do \textit{SlackBuild}. Neste exemplo foram passados apenas dois par�metros:

\begin{description}
 \item[SLACKBUILD AUTHOR] nome do autor;
 \item[DOWNLOAD FOLDER URL] url completa da fonte do pacote.
 \end{description}

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} 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}, 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.
\end{verbatim}

\noindent a leitura do par�metro \textit{PAR�METRO TEST} retornar�:

\begin{verbatim}
Este par�metro � um teste            # Este coment�rio ser� lido.
\end{verbatim}

Segue abaixo uma breve descri��o dos par�metros utilizados pelo modelo \textit{generic.mkSlackBuild}.

\subsubsection{SLACKBUILD AUTHOR e SLACKBUILD AUTHOR INITIALS}

O par�metro \textit{SLACKBUILD AUTHOR} deve conter o nome ou apelido do respons�vel pelo \textit{SlackBuild}. A declara��o deste par�metro � obrigat�ria e sem ele o \textit{mkbuild} ir� interromper a constru��o do \textit{SlackBuild}.

\begin{verbatim}
[[SLACKBUILD AUTHOR]]="Adalberto Sim�o Nader"
\end{verbatim}

O par�metro \textit{SLACKBUILD AUTHOR INITIALS} � constru�do a partir da primeira letra de cada nome passado pelo par�metro \textit{SLACKBUILD AUTHOR}, em letras min�sculas. Neste caso a assinatura ser� "\verb!asn!", as iniciais de \textit{Adalberto Sim�o Nader}.

Caso deseje passa outro valor basta adicionar a linha abaixo, ao arquivo de par�metros.

\begin{verbatim}
[[SLACKBUILD AUTHOR INITIALS]]="adal"
\end{verbatim}


\subsubsection{DOWNLOAD FOLDER URL}

O par�metro \textit{DOWNLOAD FOLDER URL} � outro par�metro obrigat�rio em um arquivo \textit{.mkbuild}. Este par�metro pode conter o endere�o completo da fonte do pacote:

\begin{verbatim}
[[DOWNLOAD FOLDER URL]]="http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/Pyrex-0.9.5.1a.tar.gz"
\end{verbatim}

Neste caso v�rias informa��es s�o removidas deste par�metro. Este par�metro pode ainda conter apenas o endere�o do diret�rio de onde a fonte poder� ser encontrada:

\begin{verbatim}
[[DOWNLOAD FOLDER URL]]="http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/"
\end{verbatim}

Neste caso, � necess�rio a defini��o de outros par�metros necess�rios para a constru��o do nome do pacote, como \textit{SOURCE NAME, PACKAGE NAME, VERSION e EXTENSION}, descritos a seguir.


\subsubsection{SOURCE NAME, PACKAGE NAME, VERSION e EXTENSION}

O \textit{SOURCE NAME} � removido do \textit{URL}, caso n�o seja passado como par�metro.

Para que o \textit{SOURCE NAME} seja carregado corretamente, � necess�rio que o nome da fonte tenha a forma padr�o:

\begin{verbatim}
NOME-DO-PROGRAMA-VER.S�O.tar.EXTENS�O
\end{verbatim}

O nome do programa pode ter v�rios campos separados por um h�fen "\verb!-!", j� a vers�o, pode possuir v�rios n�meros, ou mesmo letras, separados por ponto e terminados por um "\verb!.tar.!". A extens�o deve vir logo ap�s o "\verb!.tar.!".

A vari�vel \textit{PACKAGE NAME}, � constru�da com o mesmo valor de \textit{SOURCE NAME}, mas em letras min�sculas.

Desta forma, a divis�o dos campos no exemplo do aplicativo Pyrex, acima, ter� o mesmo valor que as declara��es dos par�metros abaixo:

\begin{verbatim}
[[SOURCE NAME]]="Pyrex"

[[PACKAGE NAME]]="pyrex"

[[VERSION]]="0.9.5.1a"

[[EXTENSION]]="gz"
\end{verbatim}

Observe que a preced�ncia � a passagem do valor como par�metro, e n�o a sua constru��o.


\subsubsection{UNPACKER e UNPACKER FLAGS}

\textit{UNPACKER} cont�m o nome do programa desempacotador das fontes, geralmente o comando "\verb!tar!", enquanto que o par�metro \textit{UNPACKER FLAGS}, carrega as flags para o desempacotador. Os seus valores padr�es s�o:

\begin{verbatim}
[[UNPACKER]]="tar"
[[UNPACKER FLAGS]]="--no-same-owner --no-same-permissions -xvf"
\end{verbatim}


\subsubsection{SOURCE NAME CONSTRUCTION STRING}

Deve conter uma string para a constru��o do nome da fonte. O valor padr�o �

\begin{verbatim}
[[SOURCE NAME CONSTRUCTION STRING]]="$SRC_NAME-$VERSION.tar.$EXTENSION"
\end{verbatim}

Observe que os par�metros passados n�o s�o processados, como ocorre em uma leitura de uma vari�vel num bash \textit{script}. Eles s�o lidos como se fossem uma cadeia de caracteres, por isto n�o tente escapar o \$ na constru��o do nome, ou o nome da fonte n�o ser� constru�do corretamente na execu��o do \textit{SlackBuild}.

Embora a vari�vel \$EXTENSION apare�a na constru��o do nome da fonte, seu valor ser� substitu�do durante a constru��o do \textit{SlackBuild} pelo \textit{mkbuild}. Por isto que n�o existe inicializa��o desta vari�vel no modelo \textit{generic.mkSlackBuild}.


\subsubsection{DECOMPRESSOR e DECOMPRESSOR TEST FLAG}

Os par�metros \textit{DECOMPRESSOR} e \textit{DECOMPRESSOR TEST FLAG} s�o determinados por an�lise do par�metro \textit{EXTENSION}, com os valores apresentados na tabela abaixo:
\\\\
\begin{tabular}{l|l|c}
\hline
EXTENSION & DECOMPRESSOR & DECOMPRESSOR TEST FLAG \\
\hline
gz, GZ   & gunzip  & -t \\
bz2, BZ2 & bunzip2 & -t \\
zip, ZIP & unzip   & -t \\
\hline
\end{tabular}

Caso possua uma fonte comprimida por um compressor diferente, passe estes par�metros pelo arquivo de par�metros, \textit{.mkbuild}.

\begin{verbatim}
[[DECOMPRESSOR]]="programa descompressor"
[[DECOMPRESSOR TEST FLAG]]="flag de teste"
\end{verbatim}


\subsubsection{DOCUMENTATION FILES}

O valor padr�o para \textit{DOCUMENTATION FILES} �

\begin{verbatim}
[[DOCUMENTATION FILES]]="NEWS TODO README AUTHORS INSTALL ChangeLog MAINTAINERS COPYING readme.*"
\end{verbatim}

Estes s�o os nomes mais comuns dos arquivos de documenta��o, que geralmente s�o disponibilizados na raiz do diret�rio das fontes dos programas. O ideal � descompactar a fonte e verificar os arquivos de documenta��o dispon�veis, para pass�-los como par�metro.


\subsubsection{PREFIX}

A maioria das fontes de programas disponibilizados atualmente, utilizam uma op��o "\verb!--prefix!" no seu \textit{configure}, para determinar o diret�rio onde o programa ser� instalado. Nas vers�es inferiores a 12.0 do \textit{Slackware} o valor desta vari�vel variava entre /usr, /opt e /usr/X11. Na vers�o 12.0, e provavelmente nas superiores, os diret�rios /opt e /usr/X11 foram removidos e todos os pacotes est�o sendo instalados em /usr. Por isto o seu valor padr�o � /usr.

\begin{verbatim}
[[PREFIX]]="/usr"
\end{verbatim}


\subsubsection{NUMBER OF JOBS}

O par�metro \textit{NUMBER OF JOBS} � usado para indicar ao comando \textit{make} o n�mero de processos que podem ser iniciados simultaneamente durante a compila��o da fonte. A grande maioria dos programas atuais podem ser compilados em dois ou mais processos simult�neos. Isto reduz sensivelmente o tempo de compila��o de um pacote, mesmo que sua m�quina possua apenas um processador. Muitos \textit{SlackBuilds} oficiais do \textit{Slackware} utilizam este par�metro configurado para "\verb!7!" processos, ou seja "\verb!-j7!". Este par�metro pode ser passado como um n�mero ou com a flag "\verb!-j!", como nos exemplos abaixo.

\begin{verbatim}
[[NUMBER OF JOBS]]="7"
\end{verbatim}

\noindent ou

\begin{verbatim}
[[NUMBER OF JOBS]]="-j7"
\end{verbatim}


\subsubsection{SLACK REQUIRED}

Este par�metro � composto pela lista de pacotes necess�rios para a constru��o do aplicativo. Estes pacotes ser�o arranjados no arquivo \textit{slack-required}. O formato para este par�metro � apresentado na linha abaixo:

\begin{verbatim}
DEPEND�NCIA_1 [CONDI��O_1] [VERS�O_1]: DEPEND�NCIA_2 [CONDI��O_2] [VERS�O_2]: DEPEND�NCIA_3 [CONDI��O_3] [VERS�O_3]: ...
\end{verbatim}

As condi��es poss�veis s�o apresentadas na tabela abaixo:
\\\\
\begin{tabular}{c|l}
\hline
CONDI��O & significado \\
\hline
=  & igual \\
>  & maior \\
>= & maior ou igual \\
\hline
\end{tabular}

Os campos \textit{CONDI��O} e \textit{VERS�O} podem ser omitidos. Cada pacote da depend�ncia deve ser separado por um ":".

Para o \textit{SLACK REQUIRED} definido com a linha:

\begin{verbatim}
[[SLACK REQUIRED]]="dep1 >= 1.1.1: dep2 >= 2.2.2:dep3:dep4:dep5 = 1.0"
\end{verbatim}

\noindent ser� gerado o arquivo \textit{slack-required} abaixo:

\begin{verbatim}
# Dependency list to Pyrex
#
# dependency [condition] [version]]
dep1            >=              1.1.1
dep2            >=              2.2.2
dep3
dep4
dep5            =               1.0
\end{verbatim}


\subsubsection{SLACKBUILD MODEL}

Este par�metro cont�m o nome do modelo utilizado para gerar os \textit{SlackBuilds}. O valor padr�o � \textit{generic.mkSlackBuild}. Outros modelos podem ser utilizados adicionando-se o arquivo do modelo no diret�rio /etc/simplepkg/defaults/mkbuild/. A linha abaixo

\begin{verbatim}
[[SLACKBUILD MODEL]]="generic.mkSlackBuild.2"
\end{verbatim}

\noindent define o modelo \textit{generic.mkSlackBuild.2} para a constru��o do \textit{SlackBuild}.


\subsubsection{SLACKBUILD PATH}

Este par�metro � necess�rio apenas para uso com a op��o "\verb!-c!", \textit{commit}. Ele indica o diret�rio, na estrutura de diret�rios do Slack.Sarava, onde o \textit{SlackBuild} constru�do dever� ser armasenado. Se este par�metro n�o for passado, o \textit{mkbuild} ir� pesquis�-lo no reposit�rio do \textit{gentoo}, pela \textit{internet}\footnote{Esta pesquisa autom�tica do mkbuild tem se mostrado pouco eficiente. Por isto � aconselh�vel verifica com um navegador a localiza��o do \textit{SlackBuild} em http://gentoo-portage.com.}. Caso n�o consiga resolver com esta pesquisa, o \textit{SlackBuild} ser� colocado em um diret�rio padr�o para \textit{scripts} n�o classificados, "\verb!others/unclassified/$PKG_NAME!".

\begin{verbatim}
[[SLACKBUILD PATH]]="dev/python/pyrex"
\end{verbatim}

A estrutura de diret�rios para armazenamento dos \textit{SlackBuilds} adotadas pelo \textit{Slack.Sarava} segue o mesmo padr�o do \textit{portage} do \textit{gentoo}.


\subsubsection{Outros Par�metros}

Outros par�metros podem ser passados para substitui��o no modelo \textit{generic.mkSlackBuild}, como o par�metro \textit{MD5SUM EXTENSION} no trecho abaixo:

\begin{verbatim}
#[[PATCH FILES]]=""
#[[MD5SUM CODE]]=""
[[MD5SUM EXTENSION]]="047574eb5d1b7848a70d4130035f1f3c"
#[[SIGNING KEY]]=""
#[[SIGNING KEY URL]]=""
#[[PATCH FILES]]=""
\end{verbatim}

Al�m destes par�metros padr�es do \textit{generic.mkSlackBuild}, qualquer outro par�metro pode ser criado e inclu�do ao modelo. Para isto � necess�rio que seu nome seja inclu�do entre duplo colchetes como no exemplo abaixo:

\begin{verbatim}
[[NEW PARAMETER]]="new value"
\end{verbatim}

O \textit{mkbuild} ir� procurar a ocorr�ncia da seq��ncia \textit{[[NEW PARAMETER]]} no modelo passado por \textit{[[SLACKBUILD MODEL]]} e ir� substitui-lo por "\verb!new value!".


\subsection{Habilitando se��es}

As se��es do modelo \textit{generic.mkSlackBuild} s�o habilitadas na se��o iniciada por "\verb!#>>!" e terminada por "\verb!#<<!", no arquivos de par�metros. Como as se��es est�o desabilitadas no modelo padr�o, \textit{generic.mkSlackBuild}, esta se��o do arquivo de par�metros tem apenas que habilitar as se��es desejadas do modelo.

\begin{verbatim}
#>> Start SlackBuild Sections:
 on: head
 on: slackbuildrc
 on: set_variables
 on: slkflags
 on: error_codes
 on: start_structure
 on: download_source
off: md5sum_download_and_check_0
off: md5sum_download_and_check_1
off: gpg_signature_check
 on: untar_source
off: patch_source
 on: configure
 on: make_package
 on: install_package
 on: strip_binaries
off: compress_manpages
off: compress_info_files
 on: install_documentation
 on: slackdesc
# esta linha � ignorada
off: postinstall_script
 on: build_package
 on: clean_builds
#<< End SlackBuild Sections
\end{verbatim}

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.


\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 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
# Untar program

# Change to temp dir
cd "$TMP"

# Uncompress e untar source
gunzip "$SRC_DIR/$SRC" | tar --no-same-owner --no-same-permissions -xvf || exit $ERROR_TAR

# Change to source dir
cd "$PKG_SRC"
#<untar_source
\end{verbatim}

\noindent ir� substituir a se��o \textit{untar\_source} do modelo \textit{generic.mkSlackBuild}, pelo conte�do definido no arquivo de par�metros acima. A �nica exce��o a esta regra � a se��o \textit{slackdesc}.

\begin{verbatim}
#>slackdesc
pyrex: Pyrex by Slack.Sarava
pyrex:
pyrex: Pyrex is a language specially designed for writing Python extension
pyrex: modules. Its designed to bridge the gap between the nice, high-level,
pyrex: easy-to-use world of Python and the messy, low-level world of C.
pyrex:
pyrex:
pyrex:
pyrex:
pyrex:
pyrex:
#<slackdesc
\end{verbatim}

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{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}

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.


\section{Ap�ndice-A}

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
        mkbuild - create SlackBuild script from .mkbuild input file

SYNOPSIS
        mkbuild [OPIONS] [mkbuild_file]

DESCRIPTION
        <mkbuild_file> input file with build rules and variables

        Input options:
            -a, --author <author_name>
                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>
                url address to source
            -pn, --pkg_name <package_name>
                package name
            -sn, --src_name <source_name>
                source name
            -pv, --pkg_version <version>
                package version
            -md, --model <SlackBuild_model>
                SlackBuild model file
            -j, --jobs <jobs_number>
                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
        -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.

AUTHOR
        Written by Rduson R. Alves

AVAILABILITY
        by svn: svn checkout svn://slack.sarava.org/simplepkg
        this mkbuild is found in branches/0.6/

REPORTING BUGS
        Report bugs to <alves_list@yahoo.com.br>

COPYRIGHT
        Copyright � 2006 Free Software Foundation, Inc.
        This is free software. You may redistribute copies of it under the
        terms of the GNU General Public License
        <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the
        extent permitted by law.
\end{verbatim}

Uma op��o interessante � a \verb!-c!, utilizada para adicionar e atualizar uma c�pia do \textit{SlackBuild} gerado na lista de \textit{SlackBuilds} local.

Slack.Sarava agradece a toda e qualquer contribui��o que possa nos ajudar a manter e a desenvolver este projeto.

\end{document}