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