File: maint-guide.pt_BR.sgml

package info (click to toggle)
maint-guide 1.2.14
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 1,256 kB
  • ctags: 27
  • sloc: makefile: 186; sh: 39
file content (1065 lines) | stat: -rw-r--r-- 77,357 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [

        <!-- textual data entities -->
        <!-- first definition wins in SGML -->
<!ENTITY % default  SYSTEM "default.ent">  %default;

]>
<!-- CVS revision of this document "$Revision: 1.20 $"  -->
<!-- CVS revision of original english document "*.**"  -->


<debiandoc>

 <book>

  <titlepag>

   <title>Guia do Novo Mantenedor Debian</title>

   <author>Josip Rodin <email/joy-mg@debian.org/
   </author>
   <author>Traduzido por: Mahdi <email/mahdi@dcc.ufmg.br/
   </author>
   <author>Revisado por: Priscilla Pimenta <email/priscilla@minaslivre.org/
   </author>

   <version>version 1.2, 6 April 2002.</version>

   <copyright>
   <copyrightsummary>Copyright &copy; 1998-2002 Josip Rodin.</copyrightsummary>

 <p>Este documento pode ser utilizado sob os termos do GNU General Public License vers�o 2 ou superior.
  <p>Este documento foi criado utilizando os seguintes documentos como exemplos:

   <p>Making a Debian Package (AKA the Debmake Manual), copyright &copy;
   1997 Jaldhar Vyas.

   <p>The New-Maintainer's Debian Packaging Howto, copyright &copy; 1997
   Will Lowe.
   </copyright>

  </titlepag>

  <toc sect>

  <chapt id="start">Come�ando do jeito certo:

  <p>O intuito deste documento � descrever a constru��o de um pacote Debian para o usu�rio comum do Debian,aspirante desenvolvedor. Ele utiliza uma linguagem bastante informal e � bem ilustrado com exemplos funcionais.
  Existe um velho ditado Romano,<em>Longum iter est per preaecepta, breve et efficax per exempla!</em> (� um longo caminho o das regras, mas curto e eficiente se exemplificado!).

  <p>Um dos fatores que fazem do Debian uma distribui��o diferenciada � o seu sistema de pacotes. Mesmo j� existindo uma vasta quantidade de programas j� distribu�dos no formato Debian, as vezes � necess�rio instalar programas que n�o o s�o.
  Voc� deve estar imaginando como criar seus pr�prios pacotes, e talvez pense que seja uma tarefa um tanto dif�cil. Bem, se voc� � realmente um iniciante no Linux, � complicado, mas se voc� j� tivesse alguma experi�ncia voc� nem estaria lendo esta documenta��o agora; :-)
  Voc� precisa saber algo sobre programa��o em Unix, mas certamente n�o precisa ser um especialista.

  <p> Uma coisa � certa, entretanto: para criar e manter pacotes Debian voc� precisa de bastante tempo. N�o cometa erros. Para o nosso sistema funcionar corretamente, os mantenedores precisam ser tanto tecnicamente competentes como aplicados.

  <p> Este documento ir� explicar passo a passo (mesmo os que a princ�pio alguns pare�am irrelevantes) e ir� ajud�-lo a criar um primeiro pacote e ganhar alguma experi�ncia na cria��o das pr�ximas distribui��es desse mesmo pacote ou at� mesmo de outros pacotes.

  <p>Novas vers�es deste documento dever�o estar sempre dispon�veis em
  <url name="http://www.debian.org/doc/maint-guide/" id="http://www.debian.org/doc/maint-guide/">
  e no pacote `<package/maint-guide-pt/'.
  <!-- Translation in <this language> is also available in the
       `<package/maint-guide-xy/' package. -->

  <sect id="needprogs">Programas que voc� precisa para o desenvolvimento:

  <p> Antes de mais nada, voc� deve estar certo de que tem instalado alguns pacotes adicionais necess�rios para o desenvolvimento. Note que a lista n�o cont�m nenhum pacote marcado 'essential' ou 'required' - supomos que voc� j� tenha tais pacotes instalados.

  <p> Esta revis�o deste documento foi atualizada para os pacotes no Debian ('sid')

  <p> Os seguintes pacotes v�m na instala��o padr�o do Debian, e voc� provavelmente j� os tem. Mesmo assim, � prudente conferir com`dpkg -s &lt;package&gt;`.

  <list>
  <item><package/dpkg-dev/ - este pacote cont�m ferramentas necess�rias para desempacotar, construir e enviar arquivos-fonte do Debian. (veja
  <manref name="dpkg-source" section="1">)

  <item><package/file/ - este pr�tico programa pode determinar o tipo de um arquivo.
  (veja <manref name="file" section="1">)

  <item><package/gcc/ - O Compilador C GNU, necess�rio se o seu programa, como muitos outros, foi escrito em C.
  (veja <manref name="gcc" section="1">)
  Este pacote ir� tamb�m instalar v�rios outros pacotes, como
  <package/binutils/ que cont�m programas utilizados para compilar e montar
  arquivos-objeto.(veja `info binutils` no pacote <package/binutils-doc/ )
  e <package/cpp/, o preprocessador C. (veja <manref name="cpp" section="1">)

  <item><package/g++/ - O Compilador C++ GNU, necess�rio se o seu programa foi escrito em C++. (veja <manref name="g++" section="1">)

  <item><package/libc6-dev/ - as bibliotecas para o C e arquivos de header que o gcc precisa criar arquivos-objeto.(veja `info libc` no pacote <package/glibc-doc/ )

  <item><package/make/ - normalmente a cria��o de um programa � feito em v�rias etapas, e assim sendo � melhor utilizar este programa para automatizar as etapas criando um Makefile ao inv�s de executar os comandos sempre. (veja `info make`)

  <item><package/patch/ - esta ferramenta � muito �til para analisar um arquivo contendo uma lista de diferen�as (criado pelo programa diff) e aplica-la no arquivo original, produzindo uma vers�o "patcheada".
  (veja <manref name="patch" section="1">)

  <item><package/perl/ - Perl � uma das linguagens de scripting interpretadas mais utilizadas nos sistemas baseados em Unix atuais. (veja <manref name="perl" section="1">)
  </list>

  <p> Voc� provavelmente vai querer instalar os seguintes pacotes tamb�m:

  <list>
  <item><package/autoconf/ e <package/automake/ - muitos dos programas atuais utilizam scripts de configura��o e Makefiles preprocessados com ajuda desses programas. (veja `info autoconf`, `info automake`)

  <item><package/dh-make/ and <package/debhelper/ - dh-make � necess�rio para criar o esqueleto do nosso pacote-exemplo e vai utilizar algumas ferramentas do debhelper para cria��o de pacotes. Elas n�o s�o essenciais para a cria��o de pacotes, mas s�o <strong>fortemente</strong> recomendadas para novos mantenedores. Elas tornam todo o processo muito mais f�cil de come�ar e controlar, no final das contas. (veja <manref name="dh_make" section="1">,
  <manref name="debhelper" section="1">, /usr/share/doc/debhelper/README)

  <item><package/devscripts/ - este pacote cont�m alguns scripts muito �teis que podem ser de interesse para os mantenedores, mas n�o s�o necess�rios para a cria��o de pacotes. (veja /usr/share/doc/devscripts/README.gz)

  <item><package/fakeroot/ - este utilit�rio permite que voc� emule ser usu�rio root, o que � necess�rio em algumas etapas do processo de cria��o. (veja <manref name="fakeroot" section="1">)

  <item><package/gnupg/ - uma ferramenta que permite que voc� <em>assine</em> digitalmente seus pacotes.
  Isto � especialmente importante se voc� quer distribui-los para outras pessoas, e voc� certamente o far� quando seu trabalho for inclu�do na distribui��o Debian. (veja <manref name="gpg" section="1">)

  <item><package/g77/ - o compilador Fortran 77 GNU, necess�rio se o seu programa foi escrito em Fortran.
  (see <manref name="g77" section="1">)

  <item><package/gpc/ - o compilador Pascal GNU, necess�rio se o seu programa foi escrito em Pascal. � bom notar tamb�m o pacote <package/fp-compiler/, o compilador Pascal gratuito, que exerce a mesma fun��o igualmente bem. (veja <manref name="gpc" section="1">, <manref name="ppc386" section="1">)

  <item><package/xutils/ - alguns programas, normalmente os criados para o X11, tamb�m utilizam esses programas para gerar Makefiles de conjuntos de fun��es de macro.(see <manref name="imake" section="1">,
  <manref name="xmkmf" section="1">)

  <item><package/lintian/ - este � o testador de pacotes Debian. Ele permite que voc� saiba se cometeu alguns dos erros mais comuns, depois de criado o pacote, e explica os erros encontrados. (veja <manref name="lintian" section="1">,
  /usr/share/doc/lintian/lintian.html/index.html)
  </list>

  <p>O seguinte pacote � uma documenta��o <em>muito</em> importante que voc� deve ler junto com este documento: 
  
  <list>
  <item><package/debian-policy/ - o Policy cont�m explana��es sobre a estrutura e conte�do do reposit�rio Debian, muitas quest�es sobre arquitetura de sistemas operacionais, a hierarquia padr�o do sistema de arquivos (que diz onde cada arquivo e diret�rio deve ficar) etc.
  Para voc�, o importante � que ele descreve os pre-requisitos que cada pacote deve satisfazer para ser inclu�do na distribui��o. (veja /usr/share/doc/debian-policy/policy.html/index.html)

  <item><package/developers-reference/ - para todos os casos n�o especificamente sobre detalhes t�cnicos de empacotamento, como a estrutura do reposit�rio, como renomear, tornar �rf�o adotar pacotes, como fazer NMUs, como tratar de bugs, onde e quando enviar os pacotes, etc.
  (veja /usr/share/doc/developers-reference/developers-reference.html/index.html)
  </list>

  <p>As curtas descri��es que s�o dadas acima servem apenas para apresentar-lhe o que cada pacote faz. Antes de continuar, por favor leia cuidadosamente a documenta��o de cada programa, pelomenos na parte do uso padr�o. Pode parecer muita coisa para estudar, mas isto lhe ser� de <em>enorme</em> valia no final.

  <p>Nota: <package/debmake/ � um pacote que cont�m alguns programas similares ao dh-make, mas seu uso espec�fico <strong>n�o �</strong>
  tratado neste documento, porque ele � <em>obsoleto</em>. Para mais informa��es, veja
  <url name="the Debmake manual" id="http://www.debian.org/~jaldhar/">
  
  <sect id="otherinfo">Outras informa��es:

  <p>Existem dois tipos de pacotes que voc� pode criar: fonte e bin�rios.
  Um pacote fonte cont�m um c�digo-fonte que voc� possa compilar.
  Um pacote bin�rio cont�m somente o programa pronto. N�o confunda os termos, como o c�digo-fonte do programa e o pacote-fonte do programa. Por favor leia outros manuais se voc� precisa de maiores informa��es sobre essa terminologia.

  <p>No Debian, o termo 'mantenedor' � usado para uma pessoa que cria pacotes, 'autor' para a pessoa que criou o programa e 'mantenedor superior' para a pessoa que atualmente mant�m o programa fora do Debian. Normalmente o autor e o mantenedor superior s�o a mesma pessoa - e as vezes at� mesmo o mantenedor � a mesma pessoa. Se voc� criou um programa, e que coloc�-lo no Debian, sinta-se a vontade para enviar-nos sua aplica��o para se tornar um mantenedor.

  <p>Depois que voc� criou o seu pacote (ou enquanto o faz), voc� ter� de se tornar um mantenedor oficial da Debian para que seu programa seja colocado na proxima distribui��o do Debian (se o seu programa � realmente �til, por que n�o?). Esse processo � tratado na Refer�ncia do Desenvolvedor (Developer's Reference). Por favor leia-o.

  <chapt id="first">Primeiros passos

  <sect id="choose">Escolha seu programa

  <p>Voc� provavelmente escolheu o pacote que quer criar. A primeira coisa que voc� precisa fazer � conferir se o pacote j� n�o est� na distribui��o. Se voc� usa a distribui��o 'stable', talvez seja melhor vc ir na
  <url name="p�gina de busca de pacotes Debian" id="http://www.debian.org/distrib/packages">.
  Se voc� usa a distribui��o 'unstable' <strong>atual</strong> confira com os seguintes comandos:
  <example>
  dpkg -s program
  dpkg -l '*program*'
  </example>

  <p>Se o pacote j� existe, bem, � s� instalar! :-) Se ele estiver �rf�o -- se seu mantenedor estiver marcado no "Grupo QA do Debian", voc� pode adot�-lo. Consulte a
  <url name="lista de pacotes �rf�os" id="http://www.debian.org/devel/wnpp/orphaned">
  e a
  <url name="lista de pacotes para ado��o" id="http://www.debian.org/devel/wnpp/rfa_bypackage">
  para verificar se o pacote est� realmente dispon�vel.

  <p>Se voc� pode adotar o pacote, pegue o seu c�digo-fonte (com algo como, 
  <tt/apt-get source packagename/) e analise-o. Este documento infelizmente n�o inclui informa��es sobre ado��o de pacotes. Felizmente voc� n�o deve ter problemas descobrindo como o pacote funciona uma vez que algu�m j� fez todo o trabalho inicial para voc�. Mesmo assim continue lendo, muito do que vem a seguir ainda ser� aplic�vel para voc�.

  <p>Se o pacote ainda n�o existe, e voc� gostaria de v�-lo no Debian, prossiga como seguinte:

  <list>
  <item>Confira se ningu�m mais est� trabalhando no pacote na
  <url name="lista de pacotes em desenvolvimento" id="http://www.de.debian.org/devel/wnpp/being_packaged">.
  Se algu�m j� est� criando-o, entre em contato com essa pessoa se voc� achar desej�vel. Sen�o - procure outro programa interessante que ningu�m mant�m ainda.
  </item>

  <item>Programas <strong>t�m</strong> de ter uma licen�a, se poss�vel gratuita como descrito no
  <url name="Guia Debian de Software Livre" id="http://www.debian.org/social_contract#guidelines">.
  Se o programa n�o concorda com alguma dessas regras, mas ainda assim pode ser distribu�do, ele ainda pode ser inclu�do nas se��es 'contrib' ou 'non-free'. Se voc� ainda n�o tem certeza sobre onde ele deve ser inclu�do, envie o texto da licen�a para <email/debian-legal@lists.debian.org/ e pe�a ajuda.
  </item>

  <item>Programas certamente <strong>n�o</strong> devem ser executados com privil�gios de root (setuid root), ou ainda melhor - eles n�o devem precisar depender de nenhum privil�gio espec�fico (nem setuid nem setgid)
  </item>

  <item>Programas n�o devem ser daemons, nem nada que tenha de ir para diret�rios */sbin, nem abrir portas como root.</item>

  <item>Programas devem estar na forma execut�vel, bibliotecas s�o mais dif�ceis de lidar.</item>

  <item>Tudo deve ser bem documentado, e/ou o c�digo tem de ser bem leg�vel e intelig�vel.</item>

  <item>Voc� deve entrar em contato com o(s) autor(es) do programa para confirmar se eles concordam com o seu empacotamento. � importante ser poss�vel o contato com o(s) autor(es) no caso de quaisquer problemas espec�ficos do programa, ent�o n�o fa�a pacotes de software sem suporte. </item>

  <item>E por �ltimo, mas n�o menos importante, voc� deve ter certeza que o tudo funciona corretamente, utilizando algum tempo.</item>
  </list>

  <p>Obviamente tudo isso s�o medidas de seguran�a, e t�m como intuito evitar usu�rios zangados com voc�, se voc� fez algo errado em algum daemon setuid root...
  Quando voc� tiver mais experi�ncia na cria��o de pacotes, voc� poder� criar tais pacotes, mas mesmo os desenvolvedores mais experientes consultam a lista debian-mentors quando em d�vida. E as pessoas l� ficar�o felizes em poder ajudar.

  <p>Para mais ajuda sobre isso, leia a Refer�ncia do Desenvolvedor (Developer's Reference).

  <sect id="getit">Pegue o programa e teste

  <p>A primeira coisa a ser feita � encontrar e baixar o pacote original. Eu presudo que voc� j� tem o c�digo-fonte pego na p�gina do autor. C�digos-fonte para software livre em Unix normalmente v�m no formato tar/gzip, com a extens�o .tar.gz, e normalmente cont�m um subdiret�rio com o nome nome_do_programa-vers�o e todos os c�digos-fonte dele dentro. Se o c�digo-fonte do seu programa vem em outro tipo de arquivamento (como por exemplo um arquivo de extens�o ".Z" ou ".zip"), desempacote-o com as ferramentas adequadas ou pe�a ajuda na lista debian-mentors se voc� n�o tem certeza de como desempacota-lo corretamente (dica: execute 'file arquivo.extens�o').

  <p>Como exemplo, eu usarei um programa chamado 'gentoo', um manipulador de arquivos para o X em GTK+. Note que o programa j� est� empacotado, e mudou bastante desde a �ltima vers�o em que este texto foi escrito.

  <p>Crie um subdiret�rio no seu home chamado 'debian' ou 'deb' ou algo que voc� ache mais apropriado (ex: ~/gentoo/ seria suficiente neste caso). Coloque o arquivo baixado dentro dele, e descompacte-o (com 'tar zxf gentoo-0.9.12.tar.tz'). Certifique-se que n�o ocorreram erros, mesmo os mais "irrelevantes", pois provavelmente poder�o ocorrer erros nos sistemas de outras pessoas, que t�m ferramentas de desempacotamento que podem ou n�o ignorar tais anomalias.

  <p>Agora voc� tem outro subdiret�rio, chamado 'gentoo-0.9.12'. Mude para esse diret�rio e leia <strong>cuidadosamente</strong> a documenta��o fornecida. Normalmente existem arquivos chamados README*, INSTALL*, *.lsm ou *.html. Voc� deve encontrar instru��es de como compilar e instalar o programa corretamente (provavelmente eles ir�o assumir que voc� quer instalar o programa no diret�rio /usr/local/bin , mas voc� n�o far� isso. Mais sobre isso ser� dito em <ref id="destdir">).

  <p>O processo varia de programa para programa, mas v�rios programas atuais vem com um script 'configure' que configura o c�digo-fonte de acordo com o seu sistema e garante que seu sistema tem condi��es de compilar o programa. Ap�s configurar o c�digo-fonte com './configure', os programas s�o normalmente compilados com 'make'. Alguns deles suportam 'make check', para rodar incluindo auto-testes. A instala��o nos devidos diret�rios de destino s�o normalmente feitos com 'make install'.
  
  <p>Agora tente compilar e executar seu programa, para garantir que ele funciona corretamente e n�o interfere em nada enquanto ele est� sendo instalado ou executado.

  <p>Normalmente voc� tamb�m pode executar 'make clean' (ou melhor ainda 'make distclean') para limpar o diret�rio de compila��o. Algumas vezes voc� pode inclusive executar um 'make uninstall' para remover todos os arquivos instalados.

  <sect id="namever">Nome do pacote e vers�o

  <p>Voc� deve come�ar empacotando com um diret�rio de c�digo-fonte completamente limpo, ou simplesmente com um c�digo-fonte rec�m descompactado.
  
  <p>Para que o pacote seja criado corretamente, voc� deve tornar o nome do programa caixa-baixa (se j� n�o for), e deve mover o diret�rio fonte para &lt;nome_do_pacote&gt;-&lt;vers�o&gt;.
  
  <p>Se o nome do programa utiliza mais de uma palavra, reduza-o para uma palavra ou abrevie-o. Por exemplo, o programa "Pequeno Editor do John para X" pode ser nomeado "xpedjohn", ou "xeditorjohn" ou qualquer outra coisa que voc� decidir, desde que o nome tenha um nome razo�vel, como 20 caracteres.

  <p>Verifique tamb�m a vers�o exata do programa (para ser inclu�da na vers�o do pacote). Se este software n�o utiliza vers�es numeradas tipo X.Y.Z, mas algo como uma data, sinta-se a vontade para utilizar essa data como a vers�o, sufixada com "0.0." (para o caso de alguem superior na manuten��o do programa resolver um dia distribuir uma vers�o tipo 1.0). Dessa forma, se a distribui��o ou imagem do programa � do dia 19/12/1998, voc� pode utilizar a vers�o como sendo 0.0.19981219.

  <p>Alguns programas nem t�m uma vers�o definida, caso o qual voc� deve entrar em contado com o mantenedor superior para certificar-se de algum outro eventual sistema de revis�o por ele utilizado.

  <sect id="dh_make">"Debianiza��o" inicial

  <p>Certifique-se que voc� est� no diret�rio do c�digo-fonte do programa e execute:

  <p><example>
  dh_make -e seu.endere�o@de.mantenedor -f ../gentoo-0.9.12.tar.gz
  </example>

  <p>Obviamente voc� deve substituir "seu.endere�o@de.mantenedor" com o seu endere�o de e-mail a ser inclu�do no changelog, outros arquivos e no nome do arquivo com o nome do seu c�digo-fonte. Veja <manref name="dh_make" section="1"> para maiores informa��es.
 
  <p>Algumas informa��es ser�o mostradas. Vai ser perguntado que tipo de pacote voc� quer criar. O gentoo � um pacote de um �nico bin�rio - ele s� cria um arquivo bin�rio, e logo um arquivo .db -, logo, vamos selecionar a primeira op��o utilizando a tecla 's'. Confira a informa��o impressa na tela e confirme pressionando &lt;enter&gt;.

  <p>Novamente, como novo mantenedor, n�o � recomend�vel que voc� crie pacotes de m�ltiplos bin�rios ou bibliotecas. N�o � muito complicado, mas exige um pouco mais de conhecimento, e assim sendo n�o ser� descrito aqui.

  <p>Note que voc� deve executar o dh_make <strong>somente uma vez</strong>, e que ele n�o se comportar� corretamente se voc� execut�-lo novamente num diret�rio j� "debianizado". Isso tamb�m significa que voc� ir� utilizar um m�todo diferente para criar uma nova revis�o ou vers�o do seu pacote no futuro. Leia mais sobre isso em <ref id="update">

  <chapt id="modify">Modificando o c�digo-fonte

  <p>Normalmente, os programa s�o instalados em subdiret�rios em /usr/local , mas os pacotes do Debian n�o devem utilizar esse diret�rio, uma vez que ele � reservado ao uso privado dos administradores do sistema. Isto significa que voc� ter� de dar uma lhada no sistema de constru��o do seu programa, normalmente come�ando com o Makefile. Este � o script <manref name="make" section="1"> que voc� ir� utilizar para automatizar a compila��o do seu programa. Para maiores informa��es sobre Makefiles, leia <ref id="rules">.

  <p>Note que se o seu programa utiliza o GNU <manref name="automake" section="1"> e/ou <manref name="autoconf" section="1">, o c�digo-fonte incluir� os arquivos Makefile.am e/ou Makefile.in, respectivamente, e voc� ter� de modificar esses arquivos tamb�m. Isto acontece pois cada execu��o do automake ir� reescrever o makefile.in com alguma informa��o gerada a partir do Makefile.am, e cada execu��o do ./configure ir� fazer o mesmo com os Makefiles, com informa��es do Makefile.in. Editando arquivos Makefile.am exigem algum conhecimento sobre o automake, que voc� pode adquirir no info do automake; ao passo que editar arquivos Makefile.in s�o mais ou menos a mesma coisa que editar Makefiles, tomando cuidado com as vari�veis (ex: qualquer string entre '@'s, como @CFLAGS@ ou @LN_S@, que s�o substitu�dos com a informa��o propriamente dita de cada execu��o do ./configure).

  <p>Note tamb�m que foge ao nosso escopo aqui descrever <em>todos</em> os detalhes sobre corre��o de c�digos, mas existem alguns problemas que normalmente s�o encontrados.

  <sect id="destdir">Instala��o em um subdiret�rio

  <p>A maioria dos programas tem algum modo de ser instalados na estrutura de diret�rio existente do seu sistema, de modo que seus bin�rios s�o inclu�dos no seu $PATH e sua documenta��o se encontre em lugares comuns. Se voc� fizer isso, entretanto, seu programa ser� instalado junto com tudo o mais que j� esteja no seu sistema. Isso tornaria dif�cil para que as ferramentas de empacotamento descobrissem quais arquivos pertencem ou n�o ao seu pacote.

  <p>Portanto voc� precisa fazer algo mais: instalar o programa dentro num subdiret�rio tempor�rio de onde as ferramentas de mantenedor ir�o trabalhar no pacote .deb. Tudo que estiver nesse diret�rio ir� ser instalado no sistema do usu�rio quando eles instalarem o pacote. A �nica diferen�a � que o dpkg vai estar instalando os arquivos no diret�rio raiz.

  <p>Este diret�rio tempor�rio � normalmente criado dentro do seu diret�rio debian/, na �rvore de diret�rios e c�digo-fonte descompactada. Ele � normalmente chamado <file>debian/nome_do_pacote</file>.

  <p>Tenha em mente que mesmo que voc� tenha que fazer o programa ser instalado em debian/nome_do_pacote, ele ainda precisa se comportar corretamente quando colocado no diret�rio raiz (ex: quando instalado do pacote .deb. Logo, voc� n�o deve deixar que o sistema de constru��o utilize strings como <tt>/home/me/gentoo-0.9.12/usr/share/gentoo</tt> nos arquivos do pacote.

  <p>Com programas que utilizam o GNU autoconf, isto ser� bastante f�cil. A maioria destes programas tem Makefiles que s�o como padr�o definidos para permitir que a instala��o seja feita num diret�rio aleat�rio, tendo em mente que /usr (por exemplo) � o prefixo can�nico. O dh_make, quando detectar que seu programa utiliza o autoconf, ir� definir os comandos para fazer tudo isso automaticamente, de forma que voc� pode inclusive saltar a leitura desta se��o, mas com outros programas, voc� provavelmente ter� de analisar e editar os Makefiles.

  <p>Eis a parte relevante do Makefile do gentoo:

  <p><example>
  # Onde colocar o bin�rio durante o 'make install'?
  BIN     = /usr/local/bin

  # Onde colocar os �cones durante o 'make install'?
  ICONS   = /usr/local/share/gentoo
  </example>

  <p>Nota-se que os arquivos est�o definidos para serem instalados em <file>/usr/local</file>. Mude tais caminhos para:
  <p><example>
  # Onde colocar o bin�rio durante o 'make install'?
  BIN     = $(DESTDIR)/usr/bin
 
  # Onde colocar os �cones durante o 'make install'?
  ICONS   = $(DESTDIR)/usr/share/gentoo
  </example>

  <p>Mas porque em tal diret�rio, e n�o algum outro? Porque os pacotes debian nunca instalam pacotes em <file>/usr/local</file> -- essa �rvore de diret�rios � reservada ao uso do administrados do sistema. Tais arquivos, no Debian, devem ser colocados em <file>/usr</file>.

  <p>A localiza��o mais exata para bin�rios, �cones, documenta��o, etc, � especificada na Hierarquia Padr�o de Sistemas de Arquivos (Filesystem Hierarchy Stanrdart - FHS - veja /usr/share/doc/debian-policy/fhs). Eu recomendo que voc� procure e leia as se��es que podem insteressar ao seu pacote.

  <p>Ent�o n�s devemos instalar o bin�rio em /usr/bin no lugar de /usr/local/bin, os manuais em /usr/share/man/man1 ao inv�s de /usr/local/man/man1, etc. Note que, como o gentoo n�o fornece um manual em seu Makefile, e o Debian-Policy exige que todo programa tenha um, n�s faremos um, mais tarde, e o instalaremos em/usr/share/man/man1.

  <p>Alguns programas n�o usam vari�veis no Makefile para definir caminhos como estes. Isto significa que voc� talvez tenha de editar alguns arquivos-fonte em C para que eles utilizem os caminhos adequados. Mas onde procurar, e exatamente o que procurar? Voc� pode resolver isso executando:

  <p><example>
  grep -nr -e 'usr/local/lib' --include='*.[c|h]' .
  </example>

  <p>O Grep ir� executar recursivamente por toda a �rvore do c�digo e dizer-lhe o nome e a linha do arquivo quando encontrar uma ocorr�ncia.

  <p>Edite esses arquivos e substitua /usr/local/* com usr/* e pronto. Tome cuidado para n�o mexer no resto do c�digo! :-)

  <p>Depois disso voc� deve encontrar o alvo de instala��o (procure pela linha come�a com 'install:', o que normalmente funciona) e renomeie todas as refer�ncias a diret�rios que n�o aqueles definidos no topo do Makefile. Antes, o alvo de instala��o do gentoo continha:

  <p><example>
  install:        gentoo
                  install ./gentoo $(BIN)
                  install icons/* $(ICONS)
                  install gentoorc-example $(HOME)/.gentoorc
  </example>

  <p>Depois da mudan�a, passou a conter:
  <example>
  install:        gentoo-target
                  install -d $(BIN) $(ICONS) $(DESTDIR)/etc
                  install ./gentoo $(BIN)
                  install -m644 icons/* $(ICONS)
                  install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc
  </example>

  <p>Voc� certamente notou que agora tem um comando <tt>install -d</tt> antes dos outros comandos semelhantes. O Makefile original n�o tinha isso porque normalmente o diret�rio /usr/local/bin e outros diret�rios j� existiam no sistema onde algu�m executasse o 'make install'. Entretante, como n�s vamos instalar o programa em nosso pr�prio diret�rio vazio (ou n�o existente), n�s teremos de criar cada um desses diret�rios.

  <p>N�s podemos inclusive adicionar outras coisas no final da regra, como a instala��o de documenta��o adicional, que os autores algumas vezes omitem:

  <p><example>
                  install -d $(DESTDIR)/usr/share/doc/gentoo/html
                  cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html
  </example>

  <p>Um leitor atento notar� que eu troquei 'gentoo' para 'gentoo-target' na linha de 'install:'. Isto � chamado de corre��o de bug n�o-relacionado. :-)

  <p>Sempre que voc� fizer mudan�as que n�o s�o especificamente relacionado ao pacote Debian, certifique-se de manda-las para o mantenedor superior para que elas possam ser inclu�das na pr�xima revis�o do programa e serem �teis para todo mundo. Lembre-se tamb�m de fazer suas mudan�as de modo n�o espec�fico ao Debian ou Linux (ou at� mesmo Unix!) antes de envi�-las -- fa�a-as port�veis. Isto tornar� suas corre��es mais f�ceis de serem aplicadas.

  <p>Note que voc� n�o tem de enviar os arquivos de debian/* ao mantenedor superior.

  <sect id="difflibs">Mudando bibliotecas

  <p>Existe um outro problema comum: bibliotecas muitas vezes variam de plataforma para plataforma. Por exemplo, um Makefile faz refer�ncia a uma biblioteca que n�o existe em sistemas Debian. Neste caso, n�s precisamos muda-la para uma biblioteca que existe no Debian, e serve pra mesma coisa.

  <p>Assim sendo, se existe alguma linha no Makefile do seu programa (ou Makefile.in) que tenha algo como isto (e o seu programa n�o compile):

  <p><example>
  LIBS = -lcurses -lalgumacoisa -lalgumaoutracoisa
  </example>

  <p>Mude-a para isso, e provavelmente funcionar�:
  <p><example>
  LIBS = -lncurses -lalgumacoisa -lalgumaoutracoisa
  </example>

  <p>(o autor percebe que este n�o � um bom exemplo, considerando que nosso pacote libncurses agora cria um symlink para libcurses.so, mas ele n�o pode encontrar nada melhor. Sugest�es s�o muito bem vindas :-)

  <chapt id="dreq">Coisas necess�rias no debian/

  <p>Agora existe um novo subdiret�rio no diret�rio-fonte do programa chamado 'debian'. Existem alguns arquivos nesse diret�rio que n�s devemos editar para personalizar o comportamento do nosso pacote. Os mais importantes deles s�o 'control', 'changelog', 'copyright' e 'rules', que s�o necess�rios para todos os pacotes.

  <sect id="control">arquivo 'control'

  <p>Este arquivo cont�m v�rios valores que o <prgn/dpkg/, <prgn/dselect/ e outras ferramentas de controle de pacotes ir�o utilizar para administrar o pacote.

  <p>Eis o arquivo de controle que o dh_make criou para n�s:

  <p><example>
  1  Source: gentoo
  2  Section: unknown
  3  Priority: optional
  4  Maintainer: Josip Rodin &lt;joy-mg@debian.org&gt;
  5  Build-Depends: debhelper (>> 3.0.0)
  6  Standards-Version: 3.5.2
  7
  8  Package: gentoo
  9  Architecture: any
  10 Depends: ${shlibs:Depends}
  11 Description: &lt;insert up to 60 chars description&gt;
  12  &lt;insert long description, indented with spaces&gt;
  </example>
(eu adicionei os n�meros das linhas)

  <p>As linhas 1-6 s�o as informa��es de controle para o pacote.

  <p>A linha 1 � o nome do pacote.

  <p>A linha 2 � a se��o da distribui��o em que o pacote ser� inclu�do.

  <p>Como voc� deve ter notado, o Debian � dividido em se��es: main (a se��o de software livre), non-free (os softwares gratuitos, mas n�o-livres) e contrib (software livre que depende de software n�o-livre). Dentro dessas, existem subse��es l�gicas que descrevem brevemente o tipo de pacote guardam. Ent�o temos 'admin' para ferramentas de administradores, 'base' para ferramentas b�sicas, 'devel' para ferramentas de programa��o, 'doc' para documenta��o, 'libs' para bibliotecas, 'mail' para clientes e daemons de email, 'net' para aplicativos e daemons de rede, 'x11' para programas gr�ficos que n�o se enquadram em outras categorias, e muitas outras.

  <p>Ent�o vamos alter�-lo para x11. (um prefixo 'main/' � impl�cito, e logo podemos omiti-lo.)

  <p>A linha 3 descreve o qu�o importante que o usu�rio instale este pacote. Leia o Debian-Policy para orienta��o no preenchimento desta lacuna. A prioridade 'optional' normalmente caber� para novos pacotes.

  <p>Se��o e prioridade s�o utilizados por frontends como o <prgn/dselect/ quando eles ordenam e selecionam os pacotes padr�o. Assim que voc� enviar o pacote para o Debian, o valor dessas duas lacunas poder� ser alterada pelos mantenedores do reposit�rio, caso o qual voc� ser� notificado por email.
  
  <p>Como este pacote � de prioridade normal e n�o entra em conflito com nada, n�s deixaremos a lacuna preenchida como 'optional'.

  <p>A linha 4 � o nome e endere�o de email do mantenedor. Certifique-se que este campo contenha um cabe�alho 'To:' v�lido para um email, porque depois que voc� enviar o pacote, o sistema de procura de bugs utilizar� ele para enviar emails de bugs para voc�. evite utilizar v�rgulas, '&'s e par�nteses.

  <p>A 5� linha cont�m a lista dos pacotes necess�rios para construir o seu pacote. Alguns pacotes, como o gcc e o make s�o impl�citos, veja o pacote <package/build-essential/ para detalhes. Se algum compilador ou ferramenta n�o-padr�o for necess�ria para construir o seu pacote, voc� deve adicion�-lo � linha 'Build-Depends'. M�ltiplas entradas s�o separadas por v�rgulas; leia a seguir para uma explica��o das depend�ncias bin�rias para saber mais sobre a sintaxe deste campo.

  <p>Voc� tamb�m pode ter Build-depends-Indep, Build-Conflicts e outros campos aqui. Estas informa��es ser�o utilizadas pelo software de cria��o autom�tica de pacotes do Debian para criar os pacotes bin�rios para outras plataformas de computadores. Veja o Debian-Policy para mais informa��es sobre as depend�ncias de compila��o e a Refer�ncia do Desenvolvedor para mais informa��es sobre outras plataformas (arquiteturas) e como portar software para elas.

  <p>Eis um hack que voc� pode utilizar para descobrir quais pacotes o seu pacotes precisa para ser compilado:
  <example>
  strace -f -o /tmp/log ./configure
  # or make instead of ./configure, if the package doesn't use autoconf
  for x in `dpkg -S $(grep open /tmp/log|\
                      perl -pe 's!.* open\(\"([^\"]*).*!$1!' |\
                      grep "^/"| sort | uniq|\
                      grep -v "^\(/tmp\|/dev\|/proc\)" ) 2>/dev/null|\
                      cut -f1 -d":"| sort | uniq`; \
        do \
          echo -n "$x (>=" `dpkg -s $x|grep ^Version|cut -f2 -d":"` "), "; \
        done
  </example>

  <p>O gentoo precisa dos pacotes <package/xlibs-dev/,<package/libgtk1.2-dev/ e <package/libglib1.2-dev/ para ser compilado, portanto vamos adiciona-los ap�s o pacote <package/debhelper/.

  <p>A linha 6 � a vers�o do padr�o do Debian-Policy que este pacote segue. As ver�es do Debian-Policy que voc� l� enquanto cria seu pacote.

  <p>A linha 8 � o nome do seu pacote bin�rio. Isto normalmente � a mesma coisa que o nome do pacote-fonte, mas n�o precisa ser necessariamente desta forma.

  <p>A linha 9 descreve as arquiteturas de CPU para que o pacote bin�rio pode ser compilado. N�s deixaremos este como 'any' pois <manref name="dpkg-gencontrol" section="1"> preencher� este campo com o valor adequado para qualquer m�quina em que este pacote seja compilado.

  <p>Se o seu pacote � independente de arquitetura (por exemplo, um script shell ou Perl, ou um documento), mude este para 'all', e leia mais tarde em <ref id="rules"> sobre a utiliza��o da regra 'binary-indep' ao inv�s da 'binary-arch' para construir o pacote.

  <p>A linha 10 mostra uma das funcionalidades mais poderosas do sistema de empacotamento do Debian. Os pacotes podem relacionar-se uns com os outros de v�rias formas. Al�m da 'Depends:', outros campos relacionais s�o 'Recommends:', 'Suggests:', 'Pre-Depends:', 'Conflicts:', 'Provides:', e 'Replaces:'.

  <p>As ferramentas de manuten��o de pacotes normalmente se comportam da mesma maneira quando lidando com essas rela��es; se n�o, ser� explicado.
  (veja <manref name="dpkg" section="8">, <manref name="dselect" section="8">,
  <manref name="apt" section="8">, <manref name="aptitude" section="1"> etc.)

  <p>Eis o que as dependencias significam:

  <p><list>
  <item>Depends:
  <p>O pacote n�o ser� instalado a menos que os pacotes de que ele depende estejam instalados. Use isso se o seu programa n�o rodar� de forma alguma (ou ter� s�rias implica��es) a menos que um pacote em particular esteja presente.</item>

  <item>Recommends:
  <p>Os Frontends como o dselect ou o aptitude ir�o perguntar-lhe se voc� deseja instalar os pacotes recomendados junto com o seu pacote; o dselect vai inclusive insistir. O dpkg e o apt-get v�o ignorar este campo. Use isso para pacotes que n�o s�o estritamente necess�rios, mas s�o tipicamente utilizados com o seu programa.</item>

  <item>Suggests:
  <p>Quando um usu�rio instala o seu programa, todos os frontends v�o pergutar-lhe se ele deseja instalar os pacotes sugeridos. O dpkg e o apt-get n�o v�o. use isso para pacotes que v�o funcionar bem com o seu programa, mas n�o s�o de forma alguma necess�rios.</item>

  <item>Pre-Depends:
  <p>Este � mais forte que o 'Depends:'. O pacote n�o ser� instalado a menos que os pacotes de que ele "pre-depende" estejam instalados <em>e corretamente configurados</em> use isso <strong>muito</strong> pouco e somente ap�s discutir isso na lista do debian-devel. Leia-se: n�o use isso. :-)</item>

  <item>Conflicts:
  <p>O pacote n�o ser� instalado at� que todos os pacotes com que ele conflite sejam removidos. Use isso se o seu programa absolutamente n�o rodar� ou causar� s�rios problemas se um pacote em particular esteja presente.</item>

  <item>Provides:
  <p>para alguns tipos de pacotes existem muitos nomes virtuais que podem ser definidos. Voc� pode obter a lista completa no arquivo /usr/share/doc/debian-policy/virtual-package-name-list.txt.gz . Use isso se o seu programa fornece uma fun��o existente em um pacote virtual. </item>

  <item>Replaces:
  <p>Use isso quando o seu programa substitui arquivos de outro pacote, ou substitui competamente outro pacote (utilizado juntamente com 'Conflicts'). Arquivos de outros pacotes listados ser�o sobreescritos com os arquivos do seu pacote.
  </item>
  </list>

  <p>Todos estes campos tem uma sintaxe uniforme. Eles s�o uma lista de nomes de pacotes separados por v�rgulas. Estes nomes de pacotes podem inclusive ser listas de nomes de pacotes alternativos, serados por simbolos de pipe (barras verticais '<tt>|</tt>).

  <p>Os campos podem restringir sua aplicabilidade a vers�es particulares de cada pacote listado. Essas vers�es s�o listadas entre par�nteses ap�s cada nome de pacote individualmente, e devem conter uma rela��o da seguinte lista seguida pelo n�mero da vers�o. As rela��es permitidas s�o:
  <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>, <tt>=</tt>, <tt>&gt;=</tt> e
  <tt>&gt;&gt;</tt> para anterior, anterior ou igual, exatamente igual, mais nova ou igual e igual, respectivamente. Por exemplo,

  <p><example>
  Depends: foo (>= 1.2), libbar1 (= 1.3.4)
  Conflicts: baz
  Recommends: libbaz4 (>> 4.0.7)
  Suggests: quux
  Replaces: quux (<< 5), quux-foo (<= 7.6)
  </example>
  
  <p>Finalmente, a �ltima funcionalidade que voc� precisa saber � ${shlibs:Depends}. Depois que seu pacote for compilado e instalado no diret�rio tempor�rio, <manref name="dh_shlibdeps" section="1"> ir� procurar por bin�rios e bibliotecas nesse diret�rio, determinar as depend�ncias de bibliotecas compartilhadas e detectar em quais pacotes elas est�o, como libc6 ou xlib6g. Ele ir� passar a lista para o <manref name="dh_gencontrol" section="1"> que ir� preencher o campo adequadamente, e voc� n�o ter� de se precupar mais com isso.

  <p>Dito tudo isto, podemos deixar a linha 'Depends:' exatamente como ela est� agora, e inserir outra linha ap�s ela com <tt>Suggests: file</tt>, pois o gentoo pode utilizar algumas funcionalidade fornecidas por este programa/pacote.

  <p>A linha 11 � uma breve descri��o. A maioria das telas das pessoas s�o de 80 colunas de largura, ent�o esta descri��o n�o deve ser maior que 60 caracteres. Eu mudarei este campo para "mantenedor de arquivos com interface completamente configur�vel para X utilizando GTK+".
  <!-- quoted should not have been translated. osamu -->

  <p>A linha 12 � onde a descri��o detalhada entra. Este deve ser um par�grafo que fornece maiores informa��es sobre o pacote. A coluna 1 de cada linha deve estar vazia. N�o podem haver linhas em branco, mas voc� pode colocar um �nico '.' (ponto) numa coluna para simular isto. Al�m disso, n�o pode haver mais de uma linha em branco ap�s a descri��o detalhada.

  <p>Finalmente, eis o arquivo de controle atualizado:

  <p><example>
  1  Source: gentoo
  2  Section: x11
  3  Priority: optional
  4  Maintainer: Josip Rodin &lt;joy-mg@debian.org&gt;
  5  Build-Depends: debhelper (>> 3.0.0), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
  6  Standards-Version: 3.5.2
  7
  8  Package: gentoo
  9  Architecture: any
  10 Depends: ${shlibs:Depends}
  11 Suggests: file
  12 Description: mantenedor de arquivos com interface completamente configur�vel para X utilizando GTK+
  13  o gentoo � um mantenedor de arquivos para Linux escrito totalmente em C puro. Ele
  14  utiliza o toolkit GTK+ para todas as suas necessidades de interface. O gentoo fornece
  15  uma interface 100% configur�vel; sem necessidade de editar arquivos de configura��o manualmente ou
  16  reiniciar o programa. O gentoo suporta a identifica��o do tipo de v�rios
  17  arquivos (utilizando extens�o, express�es regulares, ou o comando 'file'),
  18  e pode exibir arquivos de diferentes tipos com diferentes cores e �cones.
  19  .
  20  O gentoo adota alguns temas do cl�ssico mantenedor de arquivos do Amiga
  21  "Directory OPUS" (escrito por Jonathan Potter).
  </example>
  (Eu adicionei os n�meros das linhas.)
  <!-- Description: should not have been translated. osamu -->

  <sect id="copyright">O arquivo `copyright'

  <p>Este arquivo cont�m informa��o sobre os recursos superiores do pacote, informa��es de copyright e licen�a. Seu formato n�o � tratado no Debian-Policy, mas seu conte�do � (se��o 12.6 "Informa��es de Copyright").

  <p>O dh_make criou o seguinte arquivo padr�o:

  <p><example>
  1  This package was debianized by Josip Rodin &lt;joy-mg@debian.org&gt; on
  2  Wed, 11 Nov 1998 21:02:14 +0100.
  3
  4  It was downloaded from &lt;fill in ftp site&gt;
  5
  6  Upstream Author(s): &lt;put author(s) name and email here&gt;
  7
  8  Copyright:
  9
  10 &lt;Must follow here&gt;
  </example>
  (Eu coloquei os n�meros das linhas)

  <p>As coisas importantes a serem adicionadas a este arquivo s�o o lugar de onde voc� pegou o pacote, as informa��es de copyright e a licen�a do pacote. Voc� deve incluir a licen�a completa, a menos que seja um software livre de licen�a comum, como GNU GPL ou LPL, ou a licen�a art�stica do BSD, onde voc� pode simplesmente fazer refer�ncia � licen�a adequada ao diret�rio /usr/share/common-licenses/ que existe em todo sistema Debian.

  <p>Eis como o arquivo de copyright do gentoo ficaria:

  <p><example>
  1  This package was debianized by Josip Rodin &lt;joy-mg@debian.org&gt; on
  2  Wed, 11 Nov 1998 21:02:14 +0100.
  3
  4  It was downloaded from: ftp://ftp.obsession.se/gentoo/
  5
  6  Upstream author: Emil Brink &lt;emil@obsession.se&gt;
  7
  8  Este software � copyright (c) 1998-99 por Emil Brink, Obsession
  9  Development.
  10
  11 Voc� � livre para distribuir este software sob os termos da
  12 GNU General Public License.
  13 Em sistemas Debian, o texto completo da GNU General Public
  14 License pode ser encontrado em '/usr/share/common-licenses/GPL'
  </example>
  (Eu adicionei os n�meros das linhas.)

  <sect id="changelog">O arquivo `changelog'

  <p>Este arquivo � necess�rio, e tem um formato especial descrito no Debian-Policy se��o 4.4 'debian/changelog'. Este formato � utilizado pelo dpkg e outros programas para obter o n�mero da vers�o, revis�o, distribui��o e urg�ncia do seu pacote.

  <p>Para voc�, tamb�m � importante, desde que � bom ter documentadas todas as mudan�as que voc� fez. Este arquivo ajudar� as pessoas que baixam o seu pacote a ver se existem quest�es sobre o pacote que eles devam saber. Ele ser� salvo como `/usr/share/doc/gentoo/changelog.Debian.gz' no pacote bin�rio.

  <p>O dh_make criou o seguinte arquivo padr�o:

  <p><example>
  1  gentoo (0.9.12-1) unstable; urgency=low
  2
  3   * Initial Release.
  4
  5  -- Josip Rodin &lt;joy-mg@debian.org&gt;  Wed, 11 Nov 1998 21:02:14 +0100
  6
  </example>
  (Eu adicionei os n�meros das linhas.)

  <p>A linha 1 � o nome do pacote, vers�o, distribui��o e urg�ncia. O nome deve ser o mesmo nome do pacote-fonte, a distribui��o pode ser ou 'unstable' (ou at� mesmo 'experimental'), e a urg�ncia n�o deve ser mudada para nada acima de 'low'. :-)
  
  <p>As linhas 3-5 s�o a entrada de log, onde voc� deve documentar as mudan�as feitas nessa revis�o do pacote (n�o as mudan�as superiores - existe um arquivo especial para este prop�sito, criado pelos autores, que voc� instalar� depois em /usr/share/doc/gentoo/changelog.gz). Novas linhas devem ser inseridas logo antes da linha mais alta que come�a com um asterisco ('*'). Voc� pode faze-lo com o <manref name="dch" section="1">, ou manualmente com um editor de texto.

  <p>Voc� ter� algo como isso, no final das contas:
  You will end up with something like this:

  <p><example>
  1  gentoo (0.9.12-1) unstable; urgency=low
  2
  3   * Initial Release.
  4   * Este � o meu primeiro pacote Debian.
  5   * Ajustado o Makefile para corrigir problemas de $DESTDIR.
  6
  7  -- Josip Rodin &lt;joy-mg@debian.org&gt; Wed, 11 Nov 1998 21:02:14 +0100
  8
  </example>
  (Eu inseri os n�meros das linhas.)

  <p>Voc� pode ler mais sobre a atualiza��o do arquivo de changelog mais tard em 
  <ref id="update">.

  <sect id="rules">O arquivo `rules'

  <p>N�s precisamos dar uma olhada nas regras exatas que o <manref name="dpkg-buildpackage" section="1"> ir� seguir para criar efetivamente o pacote. Este arquivo �, na verdade, outro Makefile, mas diferente do fornecido pelo autor do c�digo-fonte. Diferentemente dos outros arquivos no debian, este arquivo tem de ser execut�vel.

  <p>Todo arquivo 'rules', como qualquer outro Makefile, consiste em v�rias regras que especificam como tratar do c�digo-fonte. Cada regra consistem em alvos, nomes de arquivos ou nomes de a��es que devem ser seguidas (ex: 'build:' ou 'install:'). Regras que voc� quer que sejam invocadas como argumentos de linhas de comando (por exemplo, './debian/rules build' ou 'make -f rules install'). Depois do nome do alvo, voc� pode listar as depend�ncias, programas ou arquivos de que a regra depende. Depois disso, podem haver quantos comandos forem necess�rios, indentados com &lt;tab&gt;. Uma nova regra come�a com a declara��o do alvo na primeira coluna. Linhas vazias e come�adas com '#'s (hashs) s�o tratadas como coment�rios e s�o ignoradas.

  <p>Voc� provavelment est� confuso agora, mas isso tudo ficar� mais claro com a an�liso do arquivo 'rules' que o dh_make nos d� como padr�o. Voc� deve tamb�m ler a info do 'make' para maiores informa��es.

  <p>A parte importante de saber sobre o arquivo 'rules' criado pelo dh_make, � que ele � somente uma sugest�o. Ele funcionar� para pacotes simples, mas para os mais complicados, n�o tenha medo de adicionar ou retirar coisas para satisfazer �s suas necessidades. A �nica coisa que n�o deve mudar s�o os nomes das regras, pois todas as ferramentas usam estes nomes, que s�o exigidos no Debian-Policy.

  <p> Eis (aproximadamente) como o debian/rules padr�o que o dh_make gerou para n�s �:

  <p><example>
&makefile;
  </example>
  (Eu adicionei os n�meros das linhas.)

  <p>Voc� provavelmente j� tem intimidade com linhas como a linha 1 de scripts shell e Perl. Ela diz ao sistema operacional que esse arquivo � para ser processado com o /usr/bin/make.

  <p>O significado das vari�veis DH_* mencionadas nas linhas 8 e 9 deve ser evidente para a breve descri��o. Para maiores informa��es sobre o DH_COMPAT leia a se��o 'N�veis de compatibilidade do Debhelper' no manual <manref name="debhelper" section="1">.

  <p>As linhas 11-16 s�o o esqueleto do suporte para par�metros do DEB_BUILD_OPTIONS, descritos no Debian-Policy se��o 10.1 'Bin�rios'. Basicamente, essas coisas controlam se os bin�rios devem ser constru�dos com a tabela de s�mbolos, ou se eles devem ser retirados na instala��o. Novamente, este � somente um esqueleto, uma dica de que voc� deve faze-lo. Voc� deve conferir como os sistemas de constru�ao superiores tratam da inclus�o da tabela de s�mbolos e da sua retirada na instala��o, ou implementar isso voc� mesmo.

  <p>Normalmente, voc� podedizer ao gcc para compilar com '-g' usando a vari�vel CFLAGS -- se este � o caso do seu pacote, extenda a vari�vel <em>concatenando</em> <tt>CFLAGS="$(CFLAGS)"</tt> � invoca��o do $(MAKE) na regra de constru��o (veja abaixo). Alternativamente, se o seu pacote usa um script de configura��o do autoconf, voc� pode pass�-lo <em>concatenando antes</em> do string acima na invoca��o do './configure' na regra de constru��o.

  <p>Para a remo��o, os programas s�o normalmente configurados para se instalarem sem a remo��o da tabela de s�mbolos, e normalmente sem uma op��o para mudar isso. Felizmente, voc� ainda tem o <manref name="dh_strip" section="1"> que ir� detectar quando o flag DEB_BUILD_OPTIONS=nostrip est� definido e sair silenciosamente.

  <p>As linhas 18-26 descrevem a regra 'build' (e sua regra-filho 'build-stamp'), que executa o make com a o Makefile pr�prio do programa para compila-lo. Vamos falar sobre o comentado exemplo docbook-to-man mais tardem em <ref id="manpage">.

  <p>A regra 'clean', como especificado nas linhas 28-36, limpa qualquer bin�rio n�o mais necess�rio ou coisas geradas automaticamente, deixadas ap�s a constru��o do pacote. Esta regra deve funcionar todas as vezes (mesmo quando a �rvore do c�digo-fonte <em/is/ cleaned up!), portanto use as op��es para for�ar (ex: para o rm, � '-f'), ou fa�a o make ignorar valores de retorno (falhas) utilizando um '-' na frente do nome do comando.

  <p>O processo de instala��o , a regra 'install', come�a na linha 38. Basicamente, ela executa a regra 'install' do Makefile do programa, mas instala ele no diret�rio <tt>$(CURDIR)/debian/gentoo</tt> - por isso especificamos $(DESTDIR) como a a raiz do diret�rio de instala��o no Makefile do gentoo.

  <p>Como os coment�rios sugerem, a regra 'binary-indep', na linha 48, � usada para construir pacotes independentes de arquitetura. Como n�s n�o temos nenhum, nada ser� feito aqui.

  <p>Na pr�xima regra - 'binary-arch', nas linhas 52-79, nas quais n�s executamos muitos utilit�rios pequenos do pacote debhelper para executar v�rias opera��es nos arquivos do seu pacote para fazer o pacote concordante com o Debian-Policy.

  <p>Se o seu pacote � um 'Architecture: all', voc� precisa incluir todos os comandos para construir o pacote na regra 'binary-indep', e deixar a regra 'binary-arch' vazia.
  
  <p>Os nomes dos programas do debhelper come�am com 'dh_', e o resto � a descri��o do que o utilit�rio faz em particular. E bastante auto-explicativo, mas eis algumas explica��es adicionais:

  <list>
  <item><manref name="dh_testdir" section="1"> confere se voc� est� no diret�rio correto (ex: o diret�rio superior do c�digo-fonte),
  <item><manref name="dh_testroot" section="1"> confere se voc� tem permiss�es de root necess�rias para os alvos 'binary-arch', 'binary-indep' e 'clean',
  <item><manref name="dh_installman" section="1"> copiar� os manuais para os devidos lugares no diret�rio de destino. Voc� s� precisa dizer onde eles est�o, relativamente ao diret�rio superior do c�digo-fonte,
  <item><manref name="dh_strip" section="1"> retira as tabelas de s�mbolos dos arquivos execut�veis e bibliotecas, para torn�-los menores.
  <item><manref name="dh_compress" section="1"> compacta os manuais e documenta��es maiores que 4kb com o <manref name="gzip" section="1">,
  <item><manref name="dh_installdeb" section="1"> copia os arquivos relacionados com o pacote (ex: os scripts de mantenedor) para o diret�rio <file>debian/gentoo/DEBIAN</file>,
  <item><manref name="dh_shlibdeps" section="1"> calcula as depend�ncias de bibliotecas compartilhadas das bibliotecas e arquivos execut�veis.
  <item><manref name="dh_gencontrol" section="1"> instala uma vers�o com ajuste-fino do arquivo de controle em <file>debian/gentoo/DEBIAN</file>,
  <item><manref name="dh_md5sums" section="1"> gera um MD5 checksum para todos os arquivos do pacote.
  </list>

  <p>Para informa��es mais completas sobre o que todos esses scripts dh_* fazem, e quais s�o suas op��es, por favor leia seus respectivos manuais. Existem alguns outros (possivelmente muito �teis) scripts dh_* que n�o s�o mencionados aqui. Se voc� precisar deles, leia a documenta��o do debhelper.

  <p>A se��o binary-arch � onde voc� realmente deve comentar ou remover quaisquer linhas que chamem funcionalidades que voc� n�o precisa. Para o gentoo, eu comentarei as linhas sobre exemplos, cron, init, man e info, simplesmente porque o gentoo n�o precisa delas. Al�m disso, na linha 68, eu irei substituir 'Changelog' com 'FIXES', porque esse � o nome real do arquivo de changelog superior.

  <p>As �ltimas duas linhas (junto com quaisquer outras n�o explicadas) s�o somente algumas coisas mais ou menos necess�rias, considerando que voc� pode ler o manual do make, e o Debian-Policy. Por enquanto, elas n�o s�o importantes de se conhecer.

  <chapt id="dother">Outros arquivo no debian/

  <p>Voc� pode notar que existem v�rios outros arquivos no subdiret�rio debian/, a maioria deles com o sufixo '.ex', o que significa que eles s�o exemplos. D� uma olhada em todos eles. Se voc� deseja, ou precisa, utilizar alguma de suas funcionalidades,

  <list>
    <item>olhe tamb�m sua documenta��o (dica: leia o Debian-Policy),
    <item>se necess�rio, modifique os arquivos para satisfazer suas necessidades,
    <item>renomeie-os para remover o sufixo '.ex', se eles o tiverem,
    <item>modifique o arquivo 'rules', se necess�rio.
  </list>

  <p>Alguns desses arquivos, os mais utilizados, s�o explicados nas se��es seguintes:

  <sect id="readme">README.Debian

  <p>Quaiquer outros detalhes ou discrep�ncias entre o pacote original e a sua vers�o debianizada deve ser documentada aqui.

  <p>O dh_make criou um arquivo padr�o, como seguinte:

  <p><example>
  gentoo for Debian
  -----------------

  &lt;notas poss�veis acerca deste pacote - se nenhuma, apague este arquivo.&gt;

   -- Josip Rodin &lt;joy-mg@debian.org&gt;, Wed, 11 Nov 1998 21:02:14 +0100
  </example>

  <p>Como n�o temos nada para colocar aqui, apagaremos o arquivo.

  <sect id="conffiles">conffiles.ex

  <p>Uma das coisas mais irritantes em software � quando voc� gasta muito tempo e esfor�o personalizando o seu programa, e uma nova vers�o dele desfaz todas as suas mudan�as. O Debian resolve esse problema marcando os arquivos de configura��es de forma que, quando voc� atualiza um pacote, voc� ser� perguntado se quer manter sua configura��o antiga ou n�o.

  <p>O modo se fazer isso num pacote � colocando o caminho completo de cada arquivo de configura��o (normalmente em /etc), um por linha, num arquivo chamado <tt/conffiles/. O gentoo tem um arquivo de configura��o, /etc/gentoorc, en�s vaos adicion�-lo no arquivo <tt/conffiles/.

  <p>Se o seu programa utiliza arquivos de configura��o mas tamb�m os sobrescreve por conta pr�pria, � melhor n�o marc�-los nos 'conffiles' pois sen�o o dpkg ir� perguntar aos usu�rios se eles querem verificar as mudan�as o tempo todo.

  <p>Se o programa que voc� est� empacotando precisa que todo usu�rio modifique o arquivo para funcionar, considere tamb�m n�o marcar o arquivo no 'conffiles'.

  <p>Voc� pode pode utilizar exemplos de arquivos de configura��o dos 'scripts de mantenedor'. Para maiores informa��es veja <ref id="maintscripts">.

  <p>Se o seu programa n�o tem arquivos de configura��es, voc� pode apagar o arquivo <tt/conffiles/ do diret�rio debian/.

  <sect id="crond">cron.d.ex

  <p>Se o seu pacote precisa agendar tarefas regularmente para funcionar adequadamente, voc� pode usar este arquivo para definir isso.

  <p>Note que isso n�o inclui rota��o de logs; para isso, veja
  <manref name="dh_installlogrotate" section="1"> e
  <manref name="logrotate" section="8">.

  <p>Se n�o, remova este arquivo.

  <sect id="dirs">dirs

  <p>Este arquivo especifica os diret�rios que n�s precisamos mas o processo de instala��o normal (make install), por algum motivo, n�o cria.

  <p>Por padr�o, ele � como seguinte:

  <p><example>
  usr/bin
  usr/sbin
  </example>

  <p>Note que a barra precedente n�o � inclu�da. N�s normalmente ter�amos alterado para ficar como seguinte:

  <p><example>
  usr/bin
  usr/man/man1
  </example>
  
  <p>mas estes diret�rios j� s�o criados no Makefile, e portanto n�o precisamos deste arquivo e vamos ent�o apag�-lo.

  <sect id="docs">docs

  <p>Este arquivo especifica os nomes dos arquivos de documenta��o que o dh_installdocs ir� instalar no diret�rio tempor�rio para n�s.

  <p>Por padr�o, ele incluir� todos os arquivos existentes no topo do diret�rio-fonte que s�o chamados 'BUGS', 'README*', 'TODO', etc.

  <p>Para o gentoo, eu tamb�m inclu� mais coisas:

  <p><example>
  BUGS
  CONFIG-CHANGES
  CREDITS
  ONEWS
  README
  README.gtkrc
  TODO
  </example>
  
  <p>N�s podemos tamb�m remover este arquivo e listas estes arquivo no comando <tt/dh_installdocs/ do arquivo <tt/rules/, como seguinte:

  <p><example>
        dh_installdocs BUGS CONFIG-CHANGES CREDITS ONEWS README \
                       README.gtkrc TODO
  </example>

  <p>Entretando, infelizmente voc� pode n�o ter arquivos deste tipo no c�digo-fonte do seu pacote. Neste caso, voc� pode remover este arquivo. Mas n�o remova a invoca��o do <tt/dh_installdocs/ do arquivo <tt/rules/ pois ele � utilizado para instalar o arquivo de <tt/copyright/ e outras coisas.

  <sect id="emacsen">emacsen-*.ex

  <p>Se o seu pacote fornece arquivos do Emacs que pode ser 'bytecompilados' no momento da instala��o do pacote, voc� pode utilizar estes arquivos para definir isso.

  <p>Eles s�o instalados no diret�rio tempor�rio pelo <manref name="dh_installemacsen" section="1">, portanto n�o se esque�a de descomentar essa linha no arquivo <tt/rules/ se voc� quer utilizar isso.

  <p>Se voc� n�o precisa destes, remova-os.

  <sect id="initd">init.d.ex

  <p>Se o seu pacote � um daemon que precisa ser executado na inicializa��o do sistema, voc� obviamente desobedeceu minha recomenda��o inicial, n�o � mesmo? :-)

  <p>Isto � meramente um esqueleto gen�rico para um script <file>/etc/init.d/</file>, e voc� provavelmente ter� de edit�-lo muito. Ele � instalado no diret�rio tempor�rio pelo <manref name="dh_installinit" section="1">.

  <p>Se voc� n�o precisa disto, remova o arquivo.

  <sect id="manpage">manpage.1.ex, manpage.sgml.ex

  <p>Seu(s) programa(s) devem ter manuais. Se n�o t�m, cada um destes arquivos s�o modelos que voc� pode preencher.

  <p>Manuis s�o normalmente escritos em <manref name="nroff" section="1">. O exemplo <tt/manpage.1.ex/ � escrito em nroff tamb�m. Voc� o manual <manref name="man" section="7"> para uma breve descri��o de como editar um destes arquivos.

  <p>Se, por outro lado, voc� prefere escrever em sgml ao inv�s de nroff, voc� pode usar o modelo <tt/manpage.sgml.ex/. Se voc� for fazer isso, voc� tem de:
  <list>
    <item>instalar o pacote <package/docbook-to-man/
    <item>adicionar o <tt/docbook-to-man/ � linha <tt/Build-Depends/ do arquivo <tt/control/
    <item>remover a o coment�rio da invoca��o do docbook-to-man na regra 'build' do seu arquivo <tt/rules/
  </list>

  <p>E lembre-se de renomear o arquivo para algo como <tt/gentoo.sgml/!

  <p>O nome do arquivo final do maual deve incluir o nome do programa que est� documentando, e portanto n�s iremos renome�-lo de 'manpage' para 'gentoo'. O nome do arquivo tamb�m inclui '.1' como o primeiro sufixo, o que significa que � um manual para um comando de usu�rio. Certifique-se de verificar que se��o �, de fato, a correta. Eis uma pequena lista de se��es de manuais.

  <p><example>
  Section |     Description       |     Notes
     1     Comandos de usu�rio      Comando execut�veis ou scripts.
     2     Chamadas de sistema      Fun��es fornecidas pelo kernel.
     3     Chamadas de biblioteca   Fun��es dentro de bibliotecas do sistema.
     4     Arquivos especiais       Normalmente encontrados em /dev
     5     Formatos de arquivo      Ex: o formato do /etc/passwd
     6     Jogos                    Ou outros programas fr�volos
     7     Pacotes de Macro         Como macros.
     8     Administra��o de sistema Programas t�picamente executados como root.
     9     Rotinas de Kernel        Chamadas internas e n�o-padronizadas.
  </example>
  
  <p>Ent�o o manual do gentoo deve ser chamado <tt/gentoo.1/. N�o existia um manual gentoo.1 no fonte original, ent�o eu o escrevi utilizando a informa��o do exemplo e da documenta��o.

  <sect id="menu">menu.ex

  <p>Usu�rios de sistemas X-Window normalmente tem um manipulador de janelas com um menu que pode ser personalizado para executar programas. Se eles tiverem o pacote do Debian <package/menu/, um conjunto de menus para programa no sistema ser� criado para eles.

  <p>Eis o arquivo <tt/menu.ex/ padr�o que o dh_make criou:
  
  <p><example>
  ?package(gentoo):needs=X11|text|vc|wm section=Apps/see-menu-manual\
    title="gentoo" command="/usr/bin/gentoo"
  </example>

  <p>O primeiro campo ap�s o caractere de dois-pontos � 'needs', e especifica que tipo de interface o programa precisa. Mude isto para uma das alternativas listadas, como 'text' ou 'X11'.

  <p>O seguinte � 'section', onde as entradas de menu e submenus devem aparecer. A lista atual de se��es est� em:
  <file>/usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1</file>

  <p>O campo 'title' � o nome do programa. Voc� pode come�ar este em caixa alta, se quiser, desde que seja curto.

  <p>Finalmente, o campo 'command' � o comando que executa o programa.

  <p>Agora n�s iremos mudar a entrada de menu para o seguinte:

  <p><example>
  ?package(gentoo): needs=X11 section=Apps/Tools title="Gentoo" command="gentoo"
  </example>

  <p>Voc� pode tamb�m adicionar outros campos como 'logtitle', 'icon', 'hints', etc.
  Veja <manref name="menufile" section="5">,
  <manref name="update-menus" section="1">
  e <file>/usr/share/doc/debian-policy/menu-policy.html/</file> para maiores informa��es.

  <sect id="watch">watch.ex

  <p>Este arquivo � utilizado para configurar os programas <manref name="uscan" section="1">
  e <manref name="uupdate" section="1">  (no pacote <package/devscripts/). Estes s�o utilizados para monitorar o site de onde voc� pegou o c�digo-fonte original.

  <p>Eis o que eu coloco nele:

  <p><example>
  # Arquivo de controle de monitoramento para o uscan
  # Site                Diret�rio        Padr�o                        Vers�o        Script
  ftp.obsession.se        /gentoo                gentoo-(.*)\.tar\.gz        debian        uupdate
  </example>

  <p>Dica: conecte � internet, e tente rodar o 'uscan' no diret�rio do programa assim que voc� criar o arquivo. E leia os manuais! :)

  <sect id="doc-base">ex.package.doc-base

  <p>Se o seu pacote tem outra documenta��o fora o manual e info, voc� deve utilizar o arquivo '<package/doc-base/' para registr�-lo, de forma que o usu�rio possa encontr�-la com, por exemplo, <manref name="dhelp" section="1">, <manref name="dwww" section="1"> ou <manref name="doccentral" section="1">.

  <p>Isto normalmente inclui arquivos HTML, PS ou PDF, distribu�dos em <file>/usr/share/doc/nome_do_pacote/</file>

  <p>Eis como ficaria o arquivo do doc-base do gentoo:

  <p><example>
  Document: gentoo
  Title: Manual do Gentoo
  Author: Emil Brink
  Abstract: Este manual descreve o que o Gentoo �, e como pode ser utilizado.
  Section: Apps/Tools

  Format: HTML
  Index: /usr/share/doc/gentoo/html/index.html
  Files: /usr/share/doc/gentoo/html/*.html
  </example>

  <p>Para maiores informa��es sobre esse formato, veja 
  <manref name="install-docs" section="8"> e o manual do <package/doc-base/,
  em <file>/usr/share/doc/doc-base/doc-base.html/</file>.

  <sect id="maintscripts">postinst.ex, preinst.ex, postrm.ex, prerm.ex

  <p>Estes arquivos s�o chamados scripts de manten��o. Eles s�o scripts que s�o postos na �rea de controle do pacote e executados pelo <prgn/dpkg/ quando seu pacote � instalado, atualizado ou removido.

  <p>Por enquanto, voc� deve evitar qualquer edi��o manual dos scripts de manuten��o se voc� puder, pois eles tendem a ficar complexos. Para maiores informa��es leia o cap�tulo 6 do Debian-Policy e analise estes arquivos de exemplo fornecidos pelo dh_make.

  <chapt id="build">Constru�ndo o pacote

  <p>Agora devemos estar prontos para construir o pacote.

  <sect id="completebuild">Reconstru��o completa

  <p>Mude para o diret�rio principal do programa e execute o seguinte comando:

  <p><example>
  dpkg-buildpackage -rfakeroot
  </example>

  <p>Isto far� tudo para voc�. Ele ir�:
  <list>
    <item>limpar a �rvore do c�digo-fonte (debian/rules clean), utilizando o <prgn/fakeroot/
    <item>construir o pacote-fonte (dpkg-source -b)
    <item>compilar o programa (debian/rules build)
    <item>construir o pacote-bin�rios (debian/rules binary), utilizando <prgn/fakeroot/
    <item>validar o c�digo-fonte arquivo <tt/.dsc/, utilizando <prgn/gnupg/
    <item>criar e validar o arquivo <tt/.changes/ para ser enviado, utilizando <prgn/dpkg-genchanges/ e <prgn/gnupg/
  </list>

  <p>A �nica entrada sua que ser� necess�ria ser� a sua frase-senha de GPG, duas vezes.

  <p>Feito tudo isso, voc� ver� os seguintes arquivos no diret�rio acima (<tt>~/debian/</tt>):

  <p><list>
  <item><em>gentoo_0.9.12.orig.tar.gz</em>

  <p>Este � o c�digo-fonte original, compactado, meramente renomeado para o acima de forma a seguir o padr�o Debian. Note que este foi criado utilizando a op��o '-f' no <prgn/dh_make/ quando n�s o executamos inicialmente.

  <item><em>gentoo_0.9.12-1.dsc</em>

  <p>Este � o resumo do conte�do do c�digo-fonte. O arquivo � gerado do seu arquivo 'control', e ser� utilizado quando o c�digo-fonte for desempacotado com o <manref name="dpkg-source" section="1">. Este arquivo � validado com o PGP, de forma que as pessoas podem ter certeza que ele � realmente o seu.

  <item><em>gentoo_0.9.12-1.diff.gz</em>

  <p>Este arquivo compactado cont�m cada uma das modifica��es que voc� fez no c�digo-fonte, no formato conhecido como "diff unificado". Ele � feito e utilizado pelo <manref name="dpkg-source" section="1">. ATEN��O: se voc� n�o nomear o pacote compactado (tarball) orignal como nomedopacote_versao.orig.tar.gz, o <prgn/dpkg-source/ ir� falhar na gera��o do arquivo .diff.gz!

  <p>Se algu�m quiser recriar o seu pacote desde o in�cio, eles podem facilmente faze-lo utilizando os tr�s arquivos acima. O procedimento de extra��o � trivial: copie os tr�s arquivos em algum lugar e execute <tt>dpkg-source -x gentoo_0.9.12-1.dsc</tt>.

  <item><em>gentoo_0.9.12-1_i386.deb</em>

  <p>Este � o seu pacote bin�rio completo. Voc� pode utilizar o <prgn/dpkg/ para instal�-lo e remov�-lo como qualquer outro pacote.

  <item><em>gentoo_0.9.12-1_i386.changes</em>

  <p>Este arquivo descreve todas as modifica��es feitas na revis�o atual do pacote, e � utilizado pelo programa de manuten��o do arquivo FTP da Debian para instalar os pacotes bin�rio e fonte. Ele � parcialmente gerado a partir do arquivo 'changelog' e do arquivo '.dsc'. Este arquivo � validado utilizando PGP, de forma que as pessoas podem ter certeza que ele � realmente seu.

  <p>A medida que voc� for trabalhando no pacote, o seu comportamento ir� mudar e novas funcionalidades ser�o adicionadas. As pessoas que baixarem o seu pacote poder�o olhar neste arquivo e rapidamente ver o que foi alterado. Os programas de manuten��o do arquivo da Debian tamb�m ir�o enviar o conte�do deste arquivo para a lista debian-devel-changes.
  </list>

  <p>Os longos strings num�ricos nos arquivos .dsc e .changes s�o as valida��es MD5 para os arquivos mencionados.
  Uma pessoa que baixar os seus arquivos podem test�-los com <manref name="md5sum" section="1"> e se os n�meros n�o coincidirem, eles saber�o que o arquivo est� corrompido ou que algu�m mexeu nele sem autoriza��o.

  <sect id="quickrebuild">Reconstru��o r�pida

  <p>Quando o pacote for grande, voc� pode n�o querer reconstru�-lo completamente toda vez que voc� mudar alguma coisa no arquivo <file>debian/rules</file>. Para fins de testes, voc� pode criar um arquivo .deb sem ter de reconstruir todo o c�digo e pacote-fonte da seguinte forma:

  <p><example>
  fakeroot debian/rules binary
  </example>

  <p>Assim que voc� terminar suas modifica��es, lembre-se de reconstruir o pacote como descrito anteriormente, o procedimento correto. Voc� pode n�o conseguir envi�-lo corretamente se voc� simplesmente enviar os arquivos .deb constru�dos dessa forma.

  <chapt id="checkit">Procurando por erros no pacote

  <p>Execute o <manref name="lintian" section="1"> no seu arquivo .changes ; este programa ir� verificar o pacote procurando por uma s�rie de erros comuns de empacotamento. O comando �:
  
  <p><example>
  lintian -i gentoo_0.9.12-1_i386.changes
  </example>
  
  <p>Obviamente voc� deve substituir o nome do arquivo .changes pelo gerado para o seu pacote. Se forem mostrados erros (linhas come�adas com E:), leia a descri��o (as linhas N:), corrija os erros, e reconstrua o pacote como descrito em <ref id="completebuild">. Se aparecerem linhas come�adas com W:, s�o advert�ncias, e voc� deve "afinar" o seu pacote ou certificar-se que as advert�ncias s�o desnecess�rias (e fazer obje��es no Lintian; veja a documenta��o para mais detalhes.).

  <p>Note que voc� pode construir o pacote com o <prgn/dpkg-buildpackage/ e executar o <prgn/lintian/ ao mesmo tempo com um s� comando com <manref name="debuild" section="1">.

  <p>Olhe dentro do pacote utilizando um manipulador de arquivos como o <manref name="mc" section="1">, ou desempacote-o num diret�rio tempor�rio utilizando o <manref name="dpkg-deb" section="1">. Procure por arquivos desnecess�rios, tanto no pacote bin�rio quanto no fonte. Muitas vezes o lixo n�o � eliminado corretamente; ajuste o seu arquivo 'rules' para compensar isso. Dicas: 'zgrep ^+++ ../gentoo_0.9.12-1.dif.gz' lhe dar� uma lista de modifica��es/adi��es nos arquivos-fonte, e 'dpkg-deb -c gentoo_0.9.12-1_i386.deb' ir� listar os arquivos no pacote bin�rio.

  <p>Instale o pacote e teste-o, ex: utilizando o comando <manref name="debi" section="1"> como root. Tente instalar e executa-lo em outras m�quinas diferentes e observe com aten��o as advert�ncias e/ou erros durante a instala��o e execu��o.

  <chapt id="upload">Enviando o pacote

  <p>Agora que voc� j� testou completamente o seu novo pacote, voc� est� pronto para come�ar a preencher o formul�rio de novo mantenedor do Debian, descrito em <url id="http://www.debian.org/devel/join/newmaint">

  <p>Assim que voc� se tornar um desenvolvedor oficial, voc� precisar� enviar o pacote para o arquivo da Debian. Voc� pode fazer isso manualmente, mas � mais f�cil usar as ferramentas de automatiza��o fornecidos, como o
  <manref name="dupload" section="1"> ou <manref name="dput" section="1">.
  Vamos descrever como � feito com o <prgn/dupload/.

  <p>Primeiro voc� tem de configurar o dupload. Voc� pode tanto editar o arquivo de configura��o global <file>/etc/dupload.conf</file>, ou ter o seu pr�prio arquivo <file>~/.dupload.conf</file> com as configura��es que voc� deseja personalizar. Coloque algo como o seguinte neste arquivo:

  <p><example>
  package config;

  $default_host = "ftp-master";

  $cfg{"ftp-master"}{"login"} = "seunomedeusuariodebian";

  $cfg{"non-us"}{"login"} = "seunomedeusuariodebian";

  1;
  </example>

  <p>Obviamente voc� deve substituir minhas configura��es pessoais pelas suas, e ler o manual 
  <manref name="dupload.conf" section="5"> para entender o que cada uma dessas op��es significa.

  <p>A op��o $default_host � a que precisa de mais aten��o -- ela determina qual file de upload ser� usada como padr�o. "ftp-master" � a prim�ria, mas � poss�vel que voc� queira usar outra mais r�pida. Para mais informa��es sobre files de upload, leia a Refer�ncia do Desenvolvedor (Developer's Reference), na se��o "Uploading a package", em <file>/usr/share/doc/developers-reference/developers-reference.html/ch-upload.en.html#s-uploading</file>

  <p>Conecte ent�o ao seu provedor de internet e execute o comando:
  
  <p><example>
  dupload gentoo_0.9.12-1_i386.changes
  </example>

  <p>O <prgn/dupload/ verifica se as valida��es MD5 dos arquivos coincidem com aquelas do arquivo .changes, e ir� advert�-lo a reconstruir o pacote como descrito em <ref id="completebuild">, caso n�o coincidam, para que o pacote possa ser devidamente enviado.

  <p>Se voc� enviar para o "ftp-master", o <prgn/dupload/ ir� pedir pela sua senha nas m�quinas da Debian, e ent�o ir� enviar os pacotes.

  <chapt id="update">Atualizando o pacote

  <sect id="newrevision">Nova revis�o Debian

  <p>Digamos que um relat�rio de bug foi preenchido contra o seu pacote, #54321, e descreve um problema que voc� pode solucionar. Para criar uma nova revis�o de pacote Debian voc� precisa:

  <list>
  <item>Corrigir o problema no pacote-fonte, � claro.

  <item>Adicionar uma nova revis�o no topo do arquivo de changelog, por exemplo com "dch -i', ou expl�citamente com "dch -v &lt;vers�o&gt;-&lt;revis�o&gt;' e ent�o inserir os coment�rio utilizando o seu editor de textos favorito.

  <p>Dica: Como obter a data no formato adequado?
  Use `822-date`, ou `date -R`.

  <item>Inclua uma breve descri��o do bug e sua solu��o na entrada do changelog, seguido por "Closes: #54321". Dessa forma, o relat�rio de bug ser� "autom�gicamente" fechado pelo software de manuten��o do arquivo no momento em que seu pacote for aceito no arquivo Debian.

  <item>Repita o que voc� fez em <ref id="completebuild">, <ref id="checkit">,e <ref id="upload">. A diferen�a � que, desta vez, o arquivo-fonte n�o ser� inclu�do, uma vez que ele n�o mudou e j� existe no arquivo da Debian.
  </list>

  <sect id="newupstream">Nova distribui��o do programa

  <p>Agora vamos considerar uma situa��o diferente, um pouco mais complicada - uma nova vers�o do software foi lan�ada, e obviamente voc� a quer empacotada. Voc� precisa fazer o seguinte:

  <list>
  <item>Baixar o novo c�digo-fonte e colocar o arquivo compactado (tarball) (ex: chamado 'gentoo-0.9.13.tar.gz') no diret�rio acima da �rvore do c�digo fonte antigo (ex: ~/debian/).

  <item>Entre no diret�rio do c�digo-fonte antigo e execute:

  <example>
  uupdate -u gentoo-0.9.13.tar.gz
  </example>

  <p>Obviamente, substitua esse nome de arquivo com o nome do seu novo c�digo-fonte do programa. O <manref name="uupdate" section="1"> ir� renomear o arquivo devidamente, tentar aplicar todas as diferen�as do arquivo .diff.gz antigo e atualizar o novo arquivo debian/changelog.

  <item>Mude para o diret�rio '../gentoo-0.9.14', a nova �rvore de c�digo-fonte, e repita o que voc� fez em <ref id="completebuild">, <ref id="checkit">, e <ref id="upload">.
  </list>

  <p>Note que se voc� definiu um arquivo 'debian/watch' como descrito em <ref id="watch">, voc� pode executar o <manref name="uscan" section="1"> para "autom�gicamente" procurar por novos c�digos-fonte, baixar eles, e executar o <prgn/uupdate/.

  <sect id="upgrading">Verificando atualiza��es de pacotes

  <p>Quando voc� constr�i uma nova vers�o de um pacote, voc� deve fazer o seguinte para verificar que o pacote pode ser atualizado de forma segura:

  <list>
    <item>atualizar o pacote antigo
    <item>reinstalar o pacote antigo, e ent�o remov�-lo
    <item>instalar o novo pacote
    <item>remov�-lo e o reinstalar novamente,
    <item>executar um "purge" nele.
  </list>

  <p>Tenha em mente que se o seu pacote j� foi previamente distribu�do no Debian, as pessoas ir�o atualizar para o seu pacote a partir da �ltima vers�o do Debian com frequ�ncia. Lembre-se de testar as atualiza��es a partir dessas vers�es tamb�m.

  <chapt id="helpme">Onde pedir ajuda

  <p>Antes de decidir pedir ajuda em algum lugar p�blico, por favor leia toda a documenta��o dispon�vel. Isso inclui
  a os arquivos em <file>/usr/share/doc/dpkg</file>, <file>/usr/share/doc/debian</file>, <file>/usr/share/doc/package/*</file>, os manuais e infos de todos os programas mencionados nesse documento.

  <p>Se voc� tem perguntas sobre o empacotamento e n�o pode encontrar respostas na documenta��o, voc� pode faze-las na lista Debian Mentors em <email/debian-mentors@lists.debian.org/. Os desenvolvedores Debian mais experientes ficar�o felizes em poder ajudar, mas leia a documenta��o antes de fazer perguntas!

  <p>Veja <url id="http://lists.debian.org/debian-mentors/"> para maiores informa��es sobre essa lista.

  <p>Quando voc� receber relat�rios de bugs (sim, relat�rios de bugs de verdade!), voc� saber� que � hora de entrar no <url name="Debian Bug Tracking System" id="http://www.debian.org/Bugs/"> e ler a documenta��o de l�, para poder lidar com os relat�rios eficientemente. Eu recomendo fortemente que voc� leia a Refer�ncia do Desenvolvedor (Developers Reference) no cap�tulo "Tratando de Bugs" (Handling Bugs", em <file>/usr/share/doc/developers-reference/developers-reference.html/ch-bug-handling.en.html</file>

  <p>Se voc� ainda tem perguntas, fa�a-as na lista do Debian Developers em <email/debian-devel@lists.debian.org/. Veja <url id="http://lists.debian.org/debian-devel/"> para maiores informa��es sobre esta lista.

  <p>Mesmo se voc� fez um bom trabalho, � hora de come�ar a rezar. Porque? Porque em poucas horas (ou dias) os usu�rios de todo o mundo come�ar�o a usar o seu pacote, e se voc� cometeu algum erro grave ser� bombardeado por milhares de usu�rios Debian irritados... Brincadeira! :-)

  <p>Relaxe e se prepare para relat�rios de bugs, pois ainda tem muito trabalho a ser feito antes que seu pacote esteja completamente de acordo com a pol�tica do Debian (novamente, leia a <em>documenta��o de verdade</em> para detalhes.). Boa sorte!

 </book>

</debiandoc>