cookutils rev 316
Add: pt doc
| author | Claudinei Pereira <claudinei@slitaz.org> |
|---|---|
| date | Wed Mar 14 02:14:00 2012 -0300 (2012-03-14) |
| parents | ca95e28d18a3 |
| children | 9109770afce4 |
| files | doc/cookutils.pt.html |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/doc/cookutils.pt.html Wed Mar 14 02:14:00 2012 -0300 1.3 @@ -0,0 +1,426 @@ 1.4 +<!DOCTYPE html> 1.5 +<html xmlns="http://www.w3.org/1999/xhtml"> 1.6 +<head> 1.7 + <title>Cookutils Documentation</title> 1.8 + <meta charset="utf-8" /> 1.9 + <link rel="stylesheet" type="text/css" href="style.css" /> 1.10 +</head> 1.11 +<body> 1.12 + 1.13 +<div id="header"> 1.14 + <h1>Documentação do Cookutils</h1> 1.15 +</div> 1.16 + 1.17 +<!-- Start content --> 1.18 +<div id="content"> 1.19 + 1.20 +<h2>SliTaz Cook & Cooker</h2> 1.21 + 1.22 +<p> 1.23 + O Cookutils fornece ferramentas e utilitários que ajudam na construção de 1.24 + pacotes para o SliTaz. Estas ferramentas são fáceis de aprender e utilizar, 1.25 + rápidas e leves. Você será capaz de criar pacotes para a distribuição em 1.26 + apenas alguns comandos. O cookutils fornece os comandos 'cook' e 1.27 + <a href="#cooker">Cooker</a>. 1.28 +</p> 1.29 +<p> 1.30 + O comando 'cook' permite a compilação e criação de pacotes, fornecendo um 1.31 + arquivo de log e checando a qualidade do pacote e do arquivo receipt. O 1.32 + Comando 'cooker' é um robô de compilação que fornece automação para a 1.33 + compilação, podendo ser usado como interface para o comando 'cook' na 1.34 + medida em que possui uma interface web/CGI que fornece os logs de criação 1.35 + de pacotes de forma simples de compreender. Os dois comandos utilizam 1.36 + do mesmo wok e arquivos de dados, assim como as informações de pacotes 1.37 + <a href="#blocked">bloqueados</a> e quebrados, assim como qualquer outra 1.38 + atividade necessária na criação de pacotes. 1.39 +</p> 1.40 +<p> 1.41 + Para informações técnicas, como estilo de código, por favor consultar o 1.42 + arquivo README encontrado nos fontes ou em /usr/share/doc/cookutils. 1.43 +</p> 1.44 + 1.45 +<h3>Utilização do comando Cook</h3> 1.46 +<p> 1.47 + O comando 'cook' fornece uma pequena ajuda pode ser mostrada com a opção 1.48 + 'usage'. Também possui algumas opções que executam tarefas especiais nos 1.49 + pacotes antes ou depois da compilação. Para obter ajuda: 1.50 +</p> 1.51 +<pre> 1.52 +# cook usage 1.53 +</pre> 1.54 + 1.55 +<h3>Howto</h3> 1.56 +<p> 1.57 + A primeira coisa que você deve ter antes de compilar pacotes é configurar 1.58 + seu ambiente. As duas formas recomandadas de de fazer isto são: compilar 1.59 + pacotes num servidor de compilação ou compilar num ambiente chroot. No caso 1.60 + de utilizar um ambiente chroot, pode-se instalar e usar o Tazdev para 1.61 + criá-lo e utilizá-lo: 1.62 +</p> 1.63 +<pre> 1.64 +# tazdev gen-chroot && tazdev chroot 1.65 +</pre> 1.66 +<p> 1.67 + Por padrão o Tazdev cria um ambiente chroot em /home/slitaz/cooking/chroot 1.68 + mas pode-se configurar outro caminho como argumento do comando. A 1.69 + localização do ambiente chroot não é importante, pois quando se entra nele 1.70 + os caminhos padrão serão utilizados, como /home/slitaz/wok para o wok ou 1.71 + /home/slitaz/log para os logs do 'cook'. Para mostrar a ajuda do tazdev: 1.72 + tazdev usage. 1.73 +</p> 1.74 +<p> 1.75 + Quando se usa o ambiente chroot há dois diretórios especiais montados 1.76 + com a opção 'bind': src e packages. Os fontes para todos os pacotes são 1.77 + salvos por padrão em /home/slitaz/src, que é montado no chroot para sua 1.78 + utilização pelos utilitários. Este método permite compartilhar os fontes 1.79 + entre vários ambiente chroot, como um para a versão 'cooking' e outro para 1.80 + a estável. O caminho padrão para o diretório de pacotes é: 1.81 + /home/slitaz/[versão]/packages. Assim, os pacotes ficam fora do chroot e 1.82 + são protegidos caso o ambiente chroot seja removido por algum erro. 1.83 +</p> 1.84 + 1.85 +<h3>Primeiros passos</h3> 1.86 +<p> 1.87 + Para começar os trabalhos de compilação, deve-se preparar o ambiente para 1.88 + o comando 'cook'. Ele se utiliza do arquivo de configuração cook.conf, 1.89 + onde podem ser informados caminhos alternativos para diretórios e 1.90 + arquivos, caso seja necessário. A opção 'setup' cria alguns diretórios e 1.91 + arquivos que guardam as informações de atividade e erro. Os arquivos 1.92 + criados são em texto puro, podendo ser editados por qualquer editor de 1.93 + texto. Para preparar o ambiente: 1.94 +</p> 1.95 +<pre> 1.96 +# cook setup 1.97 +</pre> 1.98 +<p> 1.99 + O comando 'setup' possui a opção --wok que permite clonar o wok do SliTaz 1.100 + durante a configuração do ambiente para o 'cook'. Mesmo não sendo um 1.101 + desenvolvedor oficial da distribuição, pode-se clonar o repositório e 1.102 + utilizar os pacotes existentes como exemplos para criar os seus próprios. 1.103 + Para configurar e clonar o wok cooking ou undigest: 1.104 +</p> 1.105 +<pre> 1.106 +# cook setup --wok 1.107 +# cook setup --undigest 1.108 +</pre> 1.109 + 1.110 +<h3>Testando o ambiente</h3> 1.111 +<p> 1.112 + O 'cook' fornece um comando de teste que cria um pacote e o compila. Isto 1.113 + permite verificar se o ambiente funciona corretamente e cria um pacote 1.114 + de exemplo com seu respectivo arquivo receipt, chamado 'cooktest', que 1.115 + pode ser removido após o teste. Para criar o pacote de teste: 1.116 +</p> 1.117 +<pre> 1.118 +# cook test 1.119 +</pre> 1.120 + 1.121 +<h3>Criando e compilando</h3> 1.122 +<p> 1.123 + Se o ambiente está configurado corretamente, pode-se iniciar a criação e 1.124 + compilação de pacotes para o SliTaz a partir do wok. Para criar um novo 1.125 + pacote com um arquivo receipt inicial (que também pode ser criado 1.126 + interativamente): 1.127 +</p> 1.128 +<pre> 1.129 +# cook new nome-do-pacote 1.130 +# cook new nome-do-pacote --interactive 1.131 +</pre> 1.132 +<p> 1.133 + Após a criação de um novo pacote, é necessária a edição do arquivo receipt 1.134 + com um editor de texto. Quando ele está pronto ou se já há um arquivo 1.135 + receipt existente, pode-se compilá-lo com o comando: 1.136 +</p> 1.137 +<pre> 1.138 +# cook nome-do-pacote 1.139 +</pre> 1.140 +<p> 1.141 + Se tudo correr bem, o pacote pronto será arquivado no diretório 1.142 + $SLITAZ/packages e os arquivos produzidos em $SLITAZ/wok/nome-do-pacote. 1.143 +</p> 1.144 + 1.145 +<h3>Compilar e instalar</h3> 1.146 +<p> 1.147 + Para compilar e instalar o pacote num único comando: 1.148 +</p> 1.149 +<pre> 1.150 +# cook nome-do-pacote --install 1.151 +</pre> 1.152 + 1.153 +<h3>Obter fontes</h3> 1.154 +<p> 1.155 + Caso se queira ou seja necessário somente o download dos arquivos fonte 1.156 + para um pacote, sem compilá-lo, pode-se utilizar a opção --getsrc: 1.157 +</p> 1.158 +<pre> 1.159 +# cook nome-do-pacote --getsrc 1.160 +</pre> 1.161 + 1.162 +<h3>Limpando resultados da compilação</h3> 1.163 +<p> 1.164 + Após a compilação e empacotamento de algum programa, permanecem no wok 1.165 + vários arquivos resultantes do processo, o que ocupa espaço em disco. 1.166 + Para limpar um único pacote: 1.167 +</p> 1.168 +<pre> 1.169 +# cook nome-do-pacote --clean 1.170 +</pre> 1.171 +<p> 1.172 + Pode-se também limpar todo o wok de uma só vez, ou apenas remover os 1.173 + arquivos fonte: 1.174 +</p> 1.175 +<pre> 1.176 +# cook clean-wok 1.177 +# cook clean-src 1.178 +</pre> 1.179 + 1.180 +<h3>Busca</h3> 1.181 +<p> 1.182 + O comando 'cook' oferece uma função de busca simples, que permite achar 1.183 + um determinado pacote no wok, utilizando 'grep' e com suporte a 1.184 + expressões regulares: 1.185 +</p> 1.186 +<pre> 1.187 +# cook search busybox 1.188 +</pre> 1.189 + 1.190 +<h3>Lista de pacotes</h3> 1.191 +<p> 1.192 + Pode-se criar uma lista de pacotes no wok, assim como uma lista de pacotes 1.193 + para ser utilizada pelo Tazpkg. Isto permite criar um repositório local 1.194 + de pacote, assim como cria uma lista de pacotes oficial que é utilizada 1.195 + nos mirrors do SliTaz. Para listar os pacotes no wok atual: 1.196 +</p> 1.197 +<pre> 1.198 +$ cook list-wok 1.199 +</pre> 1.200 +<p> 1.201 + Ao se criar uma lista de pacotes, o 'cook' verifica se há um repositório 1.202 + de variantes (flavors) em /home/slitaz/flavors. Caso haja, ele irá 1.203 + compactar as variantes usando a lista de pacotes mais recente. Para 1.204 + criar uma lista de pacotes e uma para ser utilizada com as variantes: 1.205 +</p> 1.206 +<pre> 1.207 +# cook pkgdb 1.208 +</pre> 1.209 + 1.210 +<a name="cooker"></a> 1.211 +<h3>O comando 'cooker'</h3> 1.212 +<p> 1.213 + O cooker é um robô de compilação, que tem por função checar por commits 1.214 + em um wok, criar uma listagem da ordem de compilação (cooklist) e compilar 1.215 + todos os pacotes. Também pode ser utilizado como interface para o comando 1.216 + 'cook' pois ambos se utilizam dos mesmos arquivos de configuração. Outra 1.217 + função é compilar uma grande lista de pacotes de uma só vez, assim como 1.218 + todos os pacotes de uma determinada variante. O cooker possui uma interface 1.219 + Web/CGI que funciona por padrão em qualquer sistema SliTaz, pois este 1.220 + fornece suporte a CGI no servidor web do busybox (httpd). 1.221 +</p> 1.222 +<p> 1.223 + O cooker fornece um pequeno texto de ajuda: 1.224 +</p> 1.225 +<pre> 1.226 +# cooker usage 1.227 +# cooker -u 1.228 +</pre> 1.229 + 1.230 +<h3>Configuração do Cooker</h3> 1.231 +<p> 1.232 + Assim como o 'cook', o 'cooker' precisa de um ambiente funcional para ser 1.233 + utilizado. A principal diferença é que o cooker necessita de dois 1.234 + diretórios wok para: um repositório mercurial limpo como referência e um 1.235 + wok de trabalho. Desta forma é simples comparar os dois woks para obter 1.236 + as modificações necessárias. Caso exista um ambiente de compilação, deve-se 1.237 + o wok existente antes de configurar o wok, pois poderá haver algum 1.238 + conflito. O comando 'setup' também instala alguns pacotes de 1.239 + desenvolvimento, que podem ser configurados no arquivo de configuração 1.240 + cook.conf e na variável SETUP_PKGS. Para configurar o ambiente: 1.241 +</p> 1.242 +<pre> 1.243 +# cooker setup 1.244 +</pre> 1.245 +<p> 1.246 + Se tudo correr bem, serão criados dois diretórios wok, os arquivos básicos 1.247 + de desenvolvimento serão instalados e todos os arquivos requeridos criados. 1.248 + O comportamento padrão é checar por commits, que pode ser testado com: 1.249 +</p> 1.250 +<pre> 1.251 +# cooker 1.252 +</pre> 1.253 + 1.254 +<h3>Compilando com o cooker</h3> 1.255 +<p> 1.256 + Há duas formas de utilizar o cooker: modificar o repositório mercurial 1.257 + wok limpo e executar o cooker sem argumentos ou compilar os pacotes 1.258 + manualmente. O cooker permite a compilação de um único pacote ou todos 1.259 + os pacotes de uma determinada categoria ou variante. Pode-se também tentar 1.260 + compilar todos os pacotes não compilados, mas deve-se ter ciência que esta 1.261 + ferramente não foi desenvolvida para suportar a compilação de centenas de 1.262 + pacotes de uma só vez. 1.263 +</p> 1.264 +<p> 1.265 + Para compilar um único pacote, a ferramente funciona mais ou menos como 1.266 + o comando 'cook nome-do-pacote', porém produz mais arquivos de log: 1.267 +</p> 1.268 +<pre> 1.269 +# cooker pkg nome-do-pacote 1.270 +</pre> 1.271 +<p> 1.272 + Para compilar mais de um pacote de uma só vez, há várias opções. Pode-se 1.273 + compilar todos os pacotes de uma variante, pode-se utilizar uma lista 1.274 + com nomes de pacotes (cooklist), um por linha, e, ainda, compilar todos os 1.275 + pacotes de uma determinada categoria: 1.276 +</p> 1.277 +<pre> 1.278 +# cooker flavor [nome] 1.279 +# cooker list [/caminho/para/cooklist] 1.280 +# cooker cat [categoria] 1.281 +</pre> 1.282 +<p> 1.283 + O cooker permite recompilar uma determinada revisão do repositório 1.284 + mercurial. Isto é útil em ambiente de produção se o robô de compilação 1.285 + for interrompido enquanto compila um determinado commit, podendo-se então 1.286 + prosseguir com compilação manual dos pacotes: 1.287 +</p> 1.288 +<pre> 1.289 +# cooker rev 9496 1.290 +</pre> 1.291 + 1.292 +<a name="blocked"></a> 1.293 +<h3>Pacotes bloqueados</h3> 1.294 +<p> 1.295 + O 'cook' e o 'cooker' utilizam uma lista de pacotes bloqueados, nos quais 1.296 + são indicados quais pacotes não compilar quando acontece algum commit ou 1.297 + ou quando uma lista de pacotes para compilação é utilizada. Isto é útil 1.298 + para um robô de compilação em ambiente de produção. Quando se bloqueia ou 1.299 + desbloqueia pacotes, pode-se deixar uma nota que será mostrada nas notas 1.300 + de compilação (cooknotes). Exemplos para bloquear algum pacote: 1.301 +</p> 1.302 +<pre> 1.303 +# cook nome-do-pacote --block 1.304 +# cooker block nome-do-pacote 1.305 +# cooker -n "Nota sobre o pacote bloqueado nome-do-pacote" 1.306 +</pre> 1.307 +<p> 1.308 + A lista de pacotes bloqueados é mostrada na interface web do cooker. Para 1.309 + desbloquear um pacote, pode-se utilizar o 'cooker' ou o 'cook': 1.310 +</p> 1.311 +<pre> 1.312 +# cook nome-do-pacote --unblock 1.313 +# cooker unblock nome-do-pacote 1.314 +</pre> 1.315 + 1.316 +<h3>Interface Web/CGI do cooker</h3> 1.317 +<p> 1.318 + Para visualizar os logs de compilação, os resultados de atividades e 1.319 + erros do processo, pode-se utilizar a interface web do cooker, localizada 1.320 + por padrão no diretório /var/www/cooker. Caso não se utilize de um ambiente 1.321 + chroot e se o servidor web httpd do buxybox estiver sendo executado, a 1.322 + interface pode ser acessada no endereço: 1.323 + <a href="http://localhost/cooker/cooker.cgi"> 1.324 + http://localhost/cooker/cooker.cgi</a> 1.325 +</p> 1.326 +<p> 1.327 + Caso se utilize de um ambiente chroot, deve-se instalar o 'cookutils' no 1.328 + sistema anfitrião (host) e modificar o caminho na variável SLITAZ. Uma 1.329 + forma padrão é possuir um chroot em: 1.330 +</p> 1.331 +<pre> 1.332 +/home/slitaz/cooking/chroot 1.333 +</pre> 1.334 +<p> 1.335 + Com o arquivo /etc/slitaz/cook.conf modificado da seguinte forma: 1.336 +</p> 1.337 +<pre> 1.338 +SLITAZ="/home/slitaz/cooking/chroot/home/slitaz" 1.339 +</pre> 1.340 +<p> 1.341 + Nota: não é obrigatória a instalação do 'cookutils' no host para usar a 1.342 + interface web. Caso o servidor web Lighttpd esteja instalado, pode-se 1.343 + copiar os arquivos 'cooker.cgi' e 'style.css' para, por exemplo, o 1.344 + diretório '~/Public' e utilizar um arquivo cook.conf modificado. 1.345 + A vantagem de instalar o 'cookutils' no host é obter atualizações 1.346 + regulares com o gerenciador de arquivos Tazpkg. Digamos que se tenha 1.347 + clonado ou baixado o cookutils: 1.348 +</p> 1.349 +<pre> 1.350 +$ cp -a cookutils/web ~/Public/cgi-bin/cooker 1.351 +$ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker 1.352 +</pre> 1.353 +<p> 1.354 + Neste caso, edita-se o arquivo de configuração 1.355 + '~/Public/cgi-bin/cooker/cook.conf' para configurar o caminho na variável 1.356 + SLITAZ para que tudo funcione. 1.357 +</p> 1.358 + 1.359 +<h3>Notas de compilação (Cooknotes)</h3> 1.360 +<p> 1.361 + As notas de compilação permitem escrever algum texto sobre o processo de 1.362 + empacotamento, sendo útil para ambientes colaborativos. Esta função foi 1.363 + criada com o intuito de permitir aos desenvolvedores do SliTaz 1.364 + compartilharem notas entre si e outros desenvolvedores. O cooker pode 1.365 + bloquear a compilação de um pacote ou recompilar um pacote manualmente, 1.366 + por exemplo. Então, pode-se criar uma nota sobre o motivo do pacote ter 1.367 + sido bloqueado ou ter sido recompilado, para que outro desenvolvedor saiba 1.368 + o que está ocorrendo. As notas de compilação são mostradas na interface 1.369 + web e podem ser checadas a partir da linha de comando: 1.370 +</p> 1.371 +<pre> 1.372 +# cooker note "Pacote nome-do-pacote bloqueado devido à alta utilização de CPU." 1.373 +# cooker notes 1.374 +</pre> 1.375 + 1.376 +<h3>Cooker como um robô de compilação</h3> 1.377 +<p> 1.378 + O 'cooker' foi criado para ser o robô de compilação do SliTaz, o que 1.379 + significa que ele monitora dois repositórios wok, atualiza o repositório 1.380 + mercurial, obtem as diferenças submetidas e compila todos os pacotes 1.381 + que foram adicionados ou modificados. A maneira mais segura e limpa de 1.382 + executar o cooker como um robô de compilação com agendador de atividades 1.383 + cron é utilizando um ambiente chroot, mas o utilitário também pode ser 1.384 + executado diretamente no sistema host, caso se queira. 1.385 +</p> 1.386 +<p> 1.387 + Para executar o cooker automaticamente, deve-se utilizar o agendador de 1.388 + tarefas cron, adicionando-se uma linha ao arquivo de configuração deste 1.389 + em /var/spool/cron/crontabs. Para configurar para ser executado a cada 1.390 + duas horas 1.391 +</p> 1.392 +<pre> 1.393 +* */2 * * * /usr/bin/cooker 1.394 +</pre> 1.395 + 1.396 +<h3>Robô de compilação iniciado durante o boot</h3> 1.397 +<p> 1.398 + O ambiente do 'cooker' e a tarefa do cron podem ser executadas durante o 1.399 + boot. Deve-se ter instalado o utilitário 'cookutils-daemon' instalado no 1.400 + sistema host e utilizar a instalação padrão para que tudo funcione 1.401 + corretamente (diretório cooking em /home/slitaz/cooking). O script daemon 1.402 + montará qualquer sistema de arquivos virtual, caso necessário, assim como 1.403 + os diretórios de fontes e de pacotes. Os arquivos fonte são localizados em 1.404 + /home/slitaz/src e montados no ambiente chroot, para que se possa 1.405 + compartilha-los entre várias versões (estável, cooking, undigest). Para 1.406 + instalar o utilitário: 1.407 +</p> 1.408 +<pre> 1.409 +# tazpkg get-install cookutils-daemon 1.410 +</pre> 1.411 +<p> 1.412 + Para iniciar o daemon deve-se possuir uma tarefa do cron agendada para 1.413 + o usuário root no ambiente chroot. O script funcionará como os outros 1.414 + daemons do sistema, podendo ser controlado com: 1.415 +</p> 1.416 +<pre> 1.417 +# /etc/init.d/cooker [start|stop|restart] 1.418 +</pre> 1.419 + 1.420 +<!-- End content --> 1.421 +</div> 1.422 + 1.423 +<div id="footer"> 1.424 + Copyright © 2011 SliTaz contributors 1.425 +</div> 1.426 + 1.427 +</body> 1.428 +</html> 1.429 +