cookutils view doc/cookutils.pt_BR.html @ rev 344
add complete doctype declaration on pt_BR doc.
| author | Claudinei Pereira <claudinei@slitaz.org> |
|---|---|
| date | Fri Mar 23 00:42:21 2012 -0300 (2012-03-23) |
| parents | 1a363d3de0a0 |
| children |
line source
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="pt" lang="pt">
4 <head>
5 <title>Documentação do Cookutils</title>
6 <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
7 <link rel="stylesheet" type="text/css" href="style.css" />
8 </head>
9 <body>
11 <div id="header">
12 <h1>Documentação do Cookutils</h1>
13 </div>
15 <!-- Start content -->
16 <div id="content">
18 <h2>SliTaz Cook & Cooker</h2>
20 <p>
21 O Cookutils fornece ferramentas e utilitários que ajudam na construção de
22 pacotes para o SliTaz. Estas ferramentas são fáceis de aprender e utilizar,
23 rápidas e leves. Você será capaz de criar pacotes para a distribuição em
24 apenas alguns comandos. O cookutils fornece os comandos 'cook' e
25 <a href="#cooker">Cooker</a>.
26 </p>
27 <p>
28 O comando 'cook' permite a compilação e criação de pacotes, fornecendo um
29 arquivo de log e checando a qualidade do pacote e do arquivo receipt. O
30 Comando 'cooker' é um robô de compilação que fornece automação para a
31 compilação, podendo ser usado como interface para o comando 'cook' na
32 medida em que possui uma interface web/CGI que fornece os logs de criação
33 de pacotes de forma simples de compreender. Os dois comandos utilizam
34 do mesmo wok e arquivos de dados, assim como as informações de pacotes
35 <a href="#blocked">bloqueados</a> e quebrados, assim como qualquer outra
36 atividade necessária na criação de pacotes.
37 </p>
38 <p>
39 Para informações técnicas, como estilo de código, por favor consultar o
40 arquivo README encontrado nos fontes ou em /usr/share/doc/cookutils.
41 </p>
43 <h3>Utilização do comando Cook</h3>
44 <p>
45 O comando 'cook' fornece uma pequena ajuda pode ser mostrada com a opção
46 'usage'. Também possui algumas opções que executam tarefas especiais nos
47 pacotes antes ou depois da compilação. Para obter ajuda:
48 </p>
49 <pre>
50 # cook usage
51 </pre>
53 <h3>Howto</h3>
54 <p>
55 A primeira coisa que você deve ter antes de compilar pacotes é configurar
56 seu ambiente. As duas formas recomandadas de de fazer isto são: compilar
57 pacotes num servidor de compilação ou compilar num ambiente chroot. No caso
58 de utilizar um ambiente chroot, pode-se instalar e usar o Tazdev para
59 criá-lo e utilizá-lo:
60 </p>
61 <pre>
62 # tazdev gen-chroot && tazdev chroot
63 </pre>
64 <p>
65 Por padrão o Tazdev cria um ambiente chroot em /home/slitaz/cooking/chroot
66 mas pode-se configurar outro caminho como argumento do comando. A
67 localização do ambiente chroot não é importante, pois quando se entra nele
68 os caminhos padrão serão utilizados, como /home/slitaz/wok para o wok ou
69 /home/slitaz/log para os logs do 'cook'. Para mostrar a ajuda do tazdev:
70 tazdev usage.
71 </p>
72 <p>
73 Quando se usa o ambiente chroot há dois diretórios especiais montados
74 com a opção 'bind': src e packages. Os fontes para todos os pacotes são
75 salvos por padrão em /home/slitaz/src, que é montado no chroot para sua
76 utilização pelos utilitários. Este método permite compartilhar os fontes
77 entre vários ambiente chroot, como um para a versão 'cooking' e outro para
78 a estável. O caminho padrão para o diretório de pacotes é:
79 /home/slitaz/[versão]/packages. Assim, os pacotes ficam fora do chroot e
80 são protegidos caso o ambiente chroot seja removido por algum erro.
81 </p>
83 <h3>Primeiros passos</h3>
84 <p>
85 Para começar os trabalhos de compilação, deve-se preparar o ambiente para
86 o comando 'cook'. Ele se utiliza do arquivo de configuração cook.conf,
87 onde podem ser informados caminhos alternativos para diretórios e
88 arquivos, caso seja necessário. A opção 'setup' cria alguns diretórios e
89 arquivos que guardam as informações de atividade e erro. Os arquivos
90 criados são em texto puro, podendo ser editados por qualquer editor de
91 texto. Para preparar o ambiente:
92 </p>
93 <pre>
94 # cook setup
95 </pre>
96 <p>
97 O comando 'setup' possui a opção --wok que permite clonar o wok do SliTaz
98 durante a configuração do ambiente para o 'cook'. Mesmo não sendo um
99 desenvolvedor oficial da distribuição, pode-se clonar o repositório e
100 utilizar os pacotes existentes como exemplos para criar os seus próprios.
101 Para configurar e clonar o wok cooking ou undigest:
102 </p>
103 <pre>
104 # cook setup --wok
105 # cook setup --undigest
106 </pre>
108 <h3>Testando o ambiente</h3>
109 <p>
110 O 'cook' fornece um comando de teste que cria um pacote e o compila. Isto
111 permite verificar se o ambiente funciona corretamente e cria um pacote
112 de exemplo com seu respectivo arquivo receipt, chamado 'cooktest', que
113 pode ser removido após o teste. Para criar o pacote de teste:
114 </p>
115 <pre>
116 # cook test
117 </pre>
119 <h3>Criando e compilando</h3>
120 <p>
121 Se o ambiente está configurado corretamente, pode-se iniciar a criação e
122 compilação de pacotes para o SliTaz a partir do wok. Para criar um novo
123 pacote com um arquivo receipt inicial (que também pode ser criado
124 interativamente):
125 </p>
126 <pre>
127 # cook new nome-do-pacote
128 # cook new nome-do-pacote --interactive
129 </pre>
130 <p>
131 Após a criação de um novo pacote, é necessária a edição do arquivo receipt
132 com um editor de texto. Quando ele está pronto ou se já há um arquivo
133 receipt existente, pode-se compilá-lo com o comando:
134 </p>
135 <pre>
136 # cook nome-do-pacote
137 </pre>
138 <p>
139 Se tudo correr bem, o pacote pronto será arquivado no diretório
140 $SLITAZ/packages e os arquivos produzidos em $SLITAZ/wok/nome-do-pacote.
141 </p>
143 <h3>Compilar e instalar</h3>
144 <p>
145 Para compilar e instalar o pacote num único comando:
146 </p>
147 <pre>
148 # cook nome-do-pacote --install
149 </pre>
151 <h3>Obter fontes</h3>
152 <p>
153 Caso se queira ou seja necessário somente o download dos arquivos fonte
154 para um pacote, sem compilá-lo, pode-se utilizar a opção --getsrc:
155 </p>
156 <pre>
157 # cook nome-do-pacote --getsrc
158 </pre>
160 <h3>Limpando resultados da compilação</h3>
161 <p>
162 Após a compilação e empacotamento de algum programa, permanecem no wok
163 vários arquivos resultantes do processo, o que ocupa espaço em disco.
164 Para limpar um único pacote:
165 </p>
166 <pre>
167 # cook nome-do-pacote --clean
168 </pre>
169 <p>
170 Pode-se também limpar todo o wok de uma só vez, ou apenas remover os
171 arquivos fonte:
172 </p>
173 <pre>
174 # cook clean-wok
175 # cook clean-src
176 </pre>
178 <h3>Busca</h3>
179 <p>
180 O comando 'cook' oferece uma função de busca simples, que permite achar
181 um determinado pacote no wok, utilizando 'grep' e com suporte a
182 expressões regulares:
183 </p>
184 <pre>
185 # cook search busybox
186 </pre>
188 <h3>Lista de pacotes</h3>
189 <p>
190 Pode-se criar uma lista de pacotes no wok, assim como uma lista de pacotes
191 para ser utilizada pelo Tazpkg. Isto permite criar um repositório local
192 de pacote, assim como cria uma lista de pacotes oficial que é utilizada
193 nos mirrors do SliTaz. Para listar os pacotes no wok atual:
194 </p>
195 <pre>
196 $ cook list-wok
197 </pre>
198 <p>
199 Ao se criar uma lista de pacotes, o 'cook' verifica se há um repositório
200 de variantes (flavors) em /home/slitaz/flavors. Caso haja, ele irá
201 compactar as variantes usando a lista de pacotes mais recente. Para
202 criar uma lista de pacotes e uma para ser utilizada com as variantes:
203 </p>
204 <pre>
205 # cook pkgdb
206 </pre>
208 <a name="cooker"></a>
209 <h3>O comando 'cooker'</h3>
210 <p>
211 O cooker é um robô de compilação, que tem por função checar por commits
212 em um wok, criar uma listagem da ordem de compilação (cooklist) e compilar
213 todos os pacotes. Também pode ser utilizado como interface para o comando
214 'cook' pois ambos se utilizam dos mesmos arquivos de configuração. Outra
215 função é compilar uma grande lista de pacotes de uma só vez, assim como
216 todos os pacotes de uma determinada variante. O cooker possui uma interface
217 Web/CGI que funciona por padrão em qualquer sistema SliTaz, pois este
218 fornece suporte a CGI no servidor web do busybox (httpd).
219 </p>
220 <p>
221 O cooker fornece um pequeno texto de ajuda:
222 </p>
223 <pre>
224 # cooker usage
225 # cooker -u
226 </pre>
228 <h3>Configuração do Cooker</h3>
229 <p>
230 Assim como o 'cook', o 'cooker' precisa de um ambiente funcional para ser
231 utilizado. A principal diferença é que o cooker necessita de dois
232 diretórios wok para: um repositório mercurial limpo como referência e um
233 wok de trabalho. Desta forma é simples comparar os dois woks para obter
234 as modificações necessárias. Caso exista um ambiente de compilação, deve-se
235 o wok existente antes de configurar o wok, pois poderá haver algum
236 conflito. O comando 'setup' também instala alguns pacotes de
237 desenvolvimento, que podem ser configurados no arquivo de configuração
238 cook.conf e na variável SETUP_PKGS. Para configurar o ambiente:
239 </p>
240 <pre>
241 # cooker setup
242 </pre>
243 <p>
244 Se tudo correr bem, serão criados dois diretórios wok, os arquivos básicos
245 de desenvolvimento serão instalados e todos os arquivos requeridos criados.
246 O comportamento padrão é checar por commits, que pode ser testado com:
247 </p>
248 <pre>
249 # cooker
250 </pre>
252 <h3>Compilando com o cooker</h3>
253 <p>
254 Há duas formas de utilizar o cooker: modificar o repositório mercurial
255 wok limpo e executar o cooker sem argumentos ou compilar os pacotes
256 manualmente. O cooker permite a compilação de um único pacote ou todos
257 os pacotes de uma determinada categoria ou variante. Pode-se também tentar
258 compilar todos os pacotes não compilados, mas deve-se ter ciência que esta
259 ferramente não foi desenvolvida para suportar a compilação de centenas de
260 pacotes de uma só vez.
261 </p>
262 <p>
263 Para compilar um único pacote, a ferramente funciona mais ou menos como
264 o comando 'cook nome-do-pacote', porém produz mais arquivos de log:
265 </p>
266 <pre>
267 # cooker pkg nome-do-pacote
268 </pre>
269 <p>
270 Para compilar mais de um pacote de uma só vez, há várias opções. Pode-se
271 compilar todos os pacotes de uma variante, pode-se utilizar uma lista
272 com nomes de pacotes (cooklist), um por linha, e, ainda, compilar todos os
273 pacotes de uma determinada categoria:
274 </p>
275 <pre>
276 # cooker flavor [nome]
277 # cooker list [/caminho/para/cooklist]
278 # cooker cat [categoria]
279 </pre>
280 <p>
281 O cooker permite recompilar uma determinada revisão do repositório
282 mercurial. Isto é útil em ambiente de produção se o robô de compilação
283 for interrompido enquanto compila um determinado commit, podendo-se então
284 prosseguir com compilação manual dos pacotes:
285 </p>
286 <pre>
287 # cooker rev 9496
288 </pre>
290 <a name="blocked"></a>
291 <h3>Pacotes bloqueados</h3>
292 <p>
293 O 'cook' e o 'cooker' utilizam uma lista de pacotes bloqueados, nos quais
294 são indicados quais pacotes não compilar quando acontece algum commit ou
295 ou quando uma lista de pacotes para compilação é utilizada. Isto é útil
296 para um robô de compilação em ambiente de produção. Quando se bloqueia ou
297 desbloqueia pacotes, pode-se deixar uma nota que será mostrada nas notas
298 de compilação (cooknotes). Exemplos para bloquear algum pacote:
299 </p>
300 <pre>
301 # cook nome-do-pacote --block
302 # cooker block nome-do-pacote
303 # cooker -n "Nota sobre o pacote bloqueado nome-do-pacote"
304 </pre>
305 <p>
306 A lista de pacotes bloqueados é mostrada na interface web do cooker. Para
307 desbloquear um pacote, pode-se utilizar o 'cooker' ou o 'cook':
308 </p>
309 <pre>
310 # cook nome-do-pacote --unblock
311 # cooker unblock nome-do-pacote
312 </pre>
314 <h3>Interface Web/CGI do cooker</h3>
315 <p>
316 Para visualizar os logs de compilação, os resultados de atividades e
317 erros do processo, pode-se utilizar a interface web do cooker, localizada
318 por padrão no diretório /var/www/cooker. Caso não se utilize de um ambiente
319 chroot e se o servidor web httpd do buxybox estiver sendo executado, a
320 interface pode ser acessada no endereço:
321 <a href="http://localhost/cooker/cooker.cgi">
322 http://localhost/cooker/cooker.cgi</a>
323 </p>
324 <p>
325 Caso se utilize de um ambiente chroot, deve-se instalar o 'cookutils' no
326 sistema anfitrião (host) e modificar o caminho na variável SLITAZ. Uma
327 forma padrão é possuir um chroot em:
328 </p>
329 <pre>
330 /home/slitaz/cooking/chroot
331 </pre>
332 <p>
333 Com o arquivo /etc/slitaz/cook.conf modificado da seguinte forma:
334 </p>
335 <pre>
336 SLITAZ="/home/slitaz/cooking/chroot/home/slitaz"
337 </pre>
338 <p>
339 Nota: não é obrigatória a instalação do 'cookutils' no host para usar a
340 interface web. Caso o servidor web Lighttpd esteja instalado, pode-se
341 copiar os arquivos 'cooker.cgi' e 'style.css' para, por exemplo, o
342 diretório '~/Public' e utilizar um arquivo cook.conf modificado.
343 A vantagem de instalar o 'cookutils' no host é obter atualizações
344 regulares com o gerenciador de arquivos Tazpkg. Digamos que se tenha
345 clonado ou baixado o cookutils:
346 </p>
347 <pre>
348 $ cp -a cookutils/web ~/Public/cgi-bin/cooker
349 $ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker
350 </pre>
351 <p>
352 Neste caso, edita-se o arquivo de configuração
353 '~/Public/cgi-bin/cooker/cook.conf' para configurar o caminho na variável
354 SLITAZ para que tudo funcione.
355 </p>
357 <h3>Notas de compilação (Cooknotes)</h3>
358 <p>
359 As notas de compilação permitem escrever algum texto sobre o processo de
360 empacotamento, sendo útil para ambientes colaborativos. Esta função foi
361 criada com o intuito de permitir aos desenvolvedores do SliTaz
362 compartilharem notas entre si e outros desenvolvedores. O cooker pode
363 bloquear a compilação de um pacote ou recompilar um pacote manualmente,
364 por exemplo. Então, pode-se criar uma nota sobre o motivo do pacote ter
365 sido bloqueado ou ter sido recompilado, para que outro desenvolvedor saiba
366 o que está ocorrendo. As notas de compilação são mostradas na interface
367 web e podem ser checadas a partir da linha de comando:
368 </p>
369 <pre>
370 # cooker note "Pacote nome-do-pacote bloqueado devido à alta utilização de CPU."
371 # cooker notes
372 </pre>
374 <h3>Cooker como um robô de compilação</h3>
375 <p>
376 O 'cooker' foi criado para ser o robô de compilação do SliTaz, o que
377 significa que ele monitora dois repositórios wok, atualiza o repositório
378 mercurial, obtem as diferenças submetidas e compila todos os pacotes
379 que foram adicionados ou modificados. A maneira mais segura e limpa de
380 executar o cooker como um robô de compilação com agendador de atividades
381 cron é utilizando um ambiente chroot, mas o utilitário também pode ser
382 executado diretamente no sistema host, caso se queira.
383 </p>
384 <p>
385 Para executar o cooker automaticamente, deve-se utilizar o agendador de
386 tarefas cron, adicionando-se uma linha ao arquivo de configuração deste
387 em /var/spool/cron/crontabs. Para configurar para ser executado a cada
388 duas horas
389 </p>
390 <pre>
391 * */2 * * * /usr/bin/cooker
392 </pre>
394 <h3>Robô de compilação iniciado durante o boot</h3>
395 <p>
396 O ambiente do 'cooker' e a tarefa do cron podem ser executadas durante o
397 boot. Deve-se ter instalado o utilitário 'cookutils-daemon' instalado no
398 sistema host e utilizar a instalação padrão para que tudo funcione
399 corretamente (diretório cooking em /home/slitaz/cooking). O script daemon
400 montará qualquer sistema de arquivos virtual, caso necessário, assim como
401 os diretórios de fontes e de pacotes. Os arquivos fonte são localizados em
402 /home/slitaz/src e montados no ambiente chroot, para que se possa
403 compartilha-los entre várias versões (estável, cooking, undigest). Para
404 instalar o utilitário:
405 </p>
406 <pre>
407 # tazpkg get-install cookutils-daemon
408 </pre>
409 <p>
410 Para iniciar o daemon deve-se possuir uma tarefa do cron agendada para
411 o usuário root no ambiente chroot. O script funcionará como os outros
412 daemons do sistema, podendo ser controlado com:
413 </p>
414 <pre>
415 # /etc/init.d/cooker [start|stop|restart]
416 </pre>
418 <!-- End content -->
419 </div>
421 <div id="footer">
422 Copyright © 2011 SliTaz contributors
423 </div>
425 </body>
426 </html>