cookutils view doc/cookutils.pt.html @ rev 1150
Show recent broken packages first
| author | Pascal Bellard <pascal.bellard@slitaz.org> |
|---|---|
| date | Sat Feb 19 15:32:45 2022 +0000 (2022-02-19) |
| parents | 24dbe04170be |
| children |
line source
1 <!DOCTYPE html>
2 <html xmlns="http://www.w3.org/1999/xhtml" lang="pt">
3 <head>
4 <meta charset="utf-8" />
5 <title>Documentação do Cookutils</title>
6 <link rel="stylesheet" type="text/css" href="../slitaz-doc.css" />
7 <script type="text/javascript" src="../slitaz-doc.js"></script>
8 </head>
9 <body>
11 <header>
12 <h1>Documentação do Cookutils</h1>
13 </header>
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 <h3 id="cooker">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 <h3 id="blocked">Pacotes bloqueados</h3>
290 <p>
291 O 'cook' e o 'cooker' utilizam uma lista de pacotes bloqueados, nos quais
292 são indicados quais pacotes não compilar quando acontece algum commit ou
293 ou quando uma lista de pacotes para compilação é utilizada. Isto é útil
294 para um robô de compilação em ambiente de produção. Quando se bloqueia ou
295 desbloqueia pacotes, pode-se deixar uma nota que será mostrada nas notas
296 de compilação (cooknotes). Exemplos para bloquear algum pacote:
297 </p>
298 <pre>
299 # cook nome-do-pacote --block
300 # cooker block nome-do-pacote
301 # cooker -n "Nota sobre o pacote bloqueado nome-do-pacote"
302 </pre>
303 <p>
304 A lista de pacotes bloqueados é mostrada na interface web do cooker. Para
305 desbloquear um pacote, pode-se utilizar o 'cooker' ou o 'cook':
306 </p>
307 <pre>
308 # cook nome-do-pacote --unblock
309 # cooker unblock nome-do-pacote
310 </pre>
312 <h3>Interface Web/CGI do cooker</h3>
313 <p>
314 Para visualizar os logs de compilação, os resultados de atividades e
315 erros do processo, pode-se utilizar a interface web do cooker, localizada
316 por padrão no diretório /var/www/cooker. Caso não se utilize de um ambiente
317 chroot e se o servidor web httpd do buxybox estiver sendo executado, a
318 interface pode ser acessada no endereço:
319 <a href="http://localhost/cooker/cooker.cgi">
320 http://localhost/cooker/cooker.cgi</a>
321 </p>
322 <p>
323 Caso se utilize de um ambiente chroot, deve-se instalar o 'cookutils' no
324 sistema anfitrião (host) e modificar o caminho na variável SLITAZ. Uma
325 forma padrão é possuir um chroot em:
326 </p>
327 <pre>
328 /home/slitaz/cooking/chroot
329 </pre>
330 <p>
331 Com o arquivo /etc/slitaz/cook.conf modificado da seguinte forma:
332 </p>
333 <pre>
334 SLITAZ="/home/slitaz/cooking/chroot/home/slitaz"
335 </pre>
336 <p>
337 Nota: não é obrigatória a instalação do 'cookutils' no host para usar a
338 interface web. Caso o servidor web Lighttpd esteja instalado, pode-se
339 copiar os arquivos 'cooker.cgi' e 'style.css' para, por exemplo, o
340 diretório '~/Public' e utilizar um arquivo cook.conf modificado.
341 A vantagem de instalar o 'cookutils' no host é obter atualizações
342 regulares com o gerenciador de arquivos Tazpkg. Digamos que se tenha
343 clonado ou baixado o cookutils:
344 </p>
345 <pre>
346 $ cp -a cookutils/web ~/Public/cgi-bin/cooker
347 $ cp -f cookutils/cook.conf ~/Public/cgi-bin/cooker
348 </pre>
349 <p>
350 Neste caso, edita-se o arquivo de configuração
351 '~/Public/cgi-bin/cooker/cook.conf' para configurar o caminho na variável
352 SLITAZ para que tudo funcione.
353 </p>
355 <h3>Notas de compilação (Cooknotes)</h3>
356 <p>
357 As notas de compilação permitem escrever algum texto sobre o processo de
358 empacotamento, sendo útil para ambientes colaborativos. Esta função foi
359 criada com o intuito de permitir aos desenvolvedores do SliTaz
360 compartilharem notas entre si e outros desenvolvedores. O cooker pode
361 bloquear a compilação de um pacote ou recompilar um pacote manualmente,
362 por exemplo. Então, pode-se criar uma nota sobre o motivo do pacote ter
363 sido bloqueado ou ter sido recompilado, para que outro desenvolvedor saiba
364 o que está ocorrendo. As notas de compilação são mostradas na interface
365 web e podem ser checadas a partir da linha de comando:
366 </p>
367 <pre>
368 # cooker note "Pacote nome-do-pacote bloqueado devido à alta utilização de CPU."
369 # cooker notes
370 </pre>
372 <h3>Cooker como um robô de compilação</h3>
373 <p>
374 O 'cooker' foi criado para ser o robô de compilação do SliTaz, o que
375 significa que ele monitora dois repositórios wok, atualiza o repositório
376 mercurial, obtem as diferenças submetidas e compila todos os pacotes
377 que foram adicionados ou modificados. A maneira mais segura e limpa de
378 executar o cooker como um robô de compilação com agendador de atividades
379 cron é utilizando um ambiente chroot, mas o utilitário também pode ser
380 executado diretamente no sistema host, caso se queira.
381 </p>
382 <p>
383 Para executar o cooker automaticamente, deve-se utilizar o agendador de
384 tarefas cron, adicionando-se uma linha ao arquivo de configuração deste
385 em /var/spool/cron/crontabs. Para configurar para ser executado a cada
386 duas horas
387 </p>
388 <pre>
389 * */2 * * * /usr/bin/cooker
390 </pre>
392 <h3>Robô de compilação iniciado durante o boot</h3>
393 <p>
394 O ambiente do 'cooker' e a tarefa do cron podem ser executadas durante o
395 boot. Deve-se ter instalado o utilitário 'cookutils-daemon' instalado no
396 sistema host e utilizar a instalação padrão para que tudo funcione
397 corretamente (diretório cooking em /home/slitaz/cooking). O script daemon
398 montará qualquer sistema de arquivos virtual, caso necessário, assim como
399 os diretórios de fontes e de pacotes. Os arquivos fonte são localizados em
400 /home/slitaz/src e montados no ambiente chroot, para que se possa
401 compartilha-los entre várias versões (estável, cooking, undigest). Para
402 instalar o utilitário:
403 </p>
404 <pre>
405 # tazpkg get-install cookutils-daemon
406 </pre>
407 <p>
408 Para iniciar o daemon deve-se possuir uma tarefa do cron agendada para
409 o usuário root no ambiente chroot. O script funcionará como os outros
410 daemons do sistema, podendo ser controlado com:
411 </p>
412 <pre>
413 # /etc/init.d/cooker [start|stop|restart]
414 </pre>
416 <!-- End content -->
417 </div>
419 <footer>
420 Copyright © <span class="year"></span> <a href="http://www.slitaz.org/">SliTaz GNU/Linux</a>
421 </footer>
423 </body>
424 </html>