[Rio-pm] MakeFile

[breno]

2012/6/7 Aureliano Guedes <guedes_1000 em hotmail.com>:
> Assim, toda distribuição, quando o autor submete ao CPAN, tem uma
> documentação. Essa documentação vai junto ao *.tar.gz?? Ela é o arquivo
> README, certo??
> Tem alguma formatação especial para o arquivo README ou eu posso escrever
> essa documentação da forma que eu preferir??
> Ela precisa estar em formato html ou pode ser escrito normal?
>

Você quer subir uma nova distribuição para o CPAN, é isso?

Peraí, tem algo errado...Essa sua mensagem só tem 1 hora, mas a sua
conta no CPAN tem uma distribuição "P50Tools" que subiu a 2 dias
atrás, já está na versão 0.5 e não tem README nem Changes. O ideal
nessas horas é perguntar *antes* de fazer, né?

Bom, enfim. Respondendo a sua pergunta: uma distribuição Perl vem com
3 arquivos essenciais de documentação:

 * README - dá informações genéricas da distribuição, em especial o
que é, como instalar e quem procurar em caso de dúvidas. Costuma ser
gerada automaticamente;

 * Changes - contém a lista de principais mudanças em cada versão.
Recomenda-se seguir o padrão em
https://metacpan.org/module/CPAN::Changes::Spec. A primeira versão
deste arquivo costuma ser criada automaticamente, e depois vc
incrementa ele manualmente a cada nova versão;

 * POD - Plain Old Documentation - documentação que você cria (ou que
é criada automaticamente pra vc) sobre cada um de seus módulos, como
decrição, lista de métodos, como utilizar, bugs, copyright, etc. POD é
uma linguagem de marcação simples baseada em tags na forma "=NNN".
Pode ficar em um arquivo separado, mas a maioria dos autores escreve
no próprio módulo.

Pode ser escrito "inline":

---------------------8<---------------------
package Bla;

=head2 new

cria o seu objeto. Recebe opcionalmente os seguintes parametros: .....

=end

sub new { ... }
--------------------->8---------------------

Ou, mais recomendado por alguns, no final do arquivo, após uma tag de __END__

---------------------8<---------------------
package Bla;

sub new { ... }

__END__

=head2 new

cria o seu objeto. Recebe opcionalmente os seguintes parametros: .....

=end
--------------------->8---------------------

Mais informações sobre o formato POD vc encontra em "perldoc perlpod".

Se tivesse usado o Module::Starter, um esqueleto de todos esses
arquivos teria sido criado para você. O Dist::Zilla também deveria ter
feito algo parecido, acho. Infelizmente não posso te ajudar nessa pq,
bem... não uso o Dist::Zilla.

Minha vez de perguntar: O que é o arquivo "mkf.pl" ? O que é o arquivo
"make"? Parecem coisas que você colocou sem querer dentro da dist. O
arquivo "MANIFEST" inclui a lista de arquivos que vão entrar no seu
.tar.gz. Retirar os arquivos dessa lista significa que você pode
usá-los sem se preocupar com eles entrando na sua distribuição. Muitos
autores preferem usar um MANIFEST.SKIP que cria um MANIFEST
automaticamente incluindo tudo menos o que vc definir no arquivo
(incluindo expressões regulares para nomes de arquivos que vc não quer
botar). O Dist::Zilla deve ter uma opção pra isso, sinceramente não me
lembro.

Mais importante: onde estão os seus testes?

Não tão importante mas que me deixou muito curioso: pq uma
distribuição para pentest se chama "P50Tools"?

[]s

-b