HACKING 8.04 KB
Newer Older
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
Desenvolvendo
=============

o Instalando dependências

  Para desenvolver o GPT é necessário instalar os seguintes programas:

  - g++ 
  - make
  - automake (v1.9 ou superior)
  - autoconf
  - libtool
  - antlr (v2.6.x ou superior)
  - pcre e pcrecpp
  - nasm

  Para satisfazer estas dependências no (K)Ubuntu ou Debian, pode-se executar
  o seguinte comando:

  # aptitude install g++ make automake1.9 autoconf libtool antlr libantlr-dev \
  > libpcrecpp0 libpcre3-dev nasm


o Baixando a última versão do GPT

  Para obter as últimas versões do código fonte do GPT, é necessário
  fazer um checkout no repositório, utilizando o subversion. Para instala-lo, use o seguinte comando:

  # aptitude install subversion 

  ex (checkout anônimo):

    $ svn checkout svn://svn.berlios.de/gpt/trunk/gpt

  Se você for um membro do projeto, deve ser autenticado.

  ex (checkout autenticado):

    $ svn checkout svn+ssh://username@svn.berlios.de/svnroot/repos/gpt/trunk/gpt

  Maiores informações na página do projeto no BerliOS:

    http://developer.berlios.de/projects/gpt


o Iniciando o desenvolvimento

  Se você estiver utilizando o código fonte do repositório, é necessário
  fazer o setup do sistema de construção com o seguinte comando:

  $ make -f Makefile.cvs

  Isto criará os Makefile.in's nescessários e o shell script "configure"
  utilizado para criar os Makefile's utilizados pelo programa "make"
  para automatizar a compilação do projeto.

  Se estiver utilizando o código fonte de uma versão específica
  (obtida por meio de um pacote tar.gz, por exemplo), o script "configure"
  já estará disponível.


  NOTA: se estiver obtendo erros nos arquivos Makefile.am ao executar
  make -f Makefile.cvs, verifique a versão do automake sendo utilizada:

    $ automake --version

  Se o comando acima informar uma versão inferior à 1.9, desinstale esta versão,
  execute manualmente o automake1.9 ou faça as devidas configurações para que
  a versão correta seja utilizada.


o Configurando e construindo

  Agora, basta seguir as instruções do arquivo INSTALL, executando o 
  "configure" com as opções desejadas e, em seguida, executando "make" e 
  "make install", se quiser instalar os arquivos no sistema.

o Realizando commits

  As mensagens de commit devem, idealmente, seguir pequenas convenções:

  -Toda mensagem de commit deve ser enviada utilizando ASCII, sem acentos.
   (pelo menos, até termos os emails em gpt-commit exibidos corretamente)

  -Toda descrição lógica deve iniciar em uma nova linha, prefixada por "-".

    Ex: Duas descrições para as modificações do arquivo A.cpp :

      $ svn ci A.cpp -m"-Utilizando algoritmo mais rápido para a função f()
      > -Adicionado classe X para lidar com erros do usuário"


  - Todas as modificações lógicas que envolvem vários arquivos devem
    ser commitadas em uma mesma leva, a não ser que um ou mais arquivos
    envolvidos contenham outras modificações. Neste último caso,
    o arquivo poderá ser commitado separadamente, mas com a mesma
    mensagem do commit da leva, além da mensagem descrevendo as 
    modificações específicas.

    Ex 1: A.cpp e B.cpp foram modificados. A.cpp teve o nome de uma função
    modificada, e B.cpp, por usar esta função, teve que ser modificado também.
    Os dois arquivos, A.cpp e B.cpp devem ser commitados em conjunto:

      $ svn ci A.cpp B.cpp -m"-Função func() renomeada para f()"


    Ex 2: A.cpp e B.cpp foram modificados. A.cpp melhorou um algoritmo e 
    modificou o nome de uma função. B.cpp, por utilizar esta função, teve que
    ser modificado também. Os dois arquivos, A.cpp e B.cpp podem ser
    commitdos separadamente:

      $ svn ci A.cpp -m"-Função func() renomeada para f()
      > -Utilizando algoritmo xyz para a funcao z()"
 
      $ svn ci B.cpp -m"-Função func() renomeada para f()"

      Note que a mesma mensagem da mudança da função foi utilizada nos dois
      commits.

   Ou em conjunto (o que ficar mais claro para quem ler os Logs :-)

      $ svn ci A.cpp B.cpp -m"-Função func() renomeada para f()
      > -Utilizando algoritmo xyz para a funcao z() em A.cpp"


  -Mensagens de modificações que resolvem bugs devem ser precedidos por BUGFIX:

     $svn ci A.cpp -m"BUGFIX: resolvido bug ao fazer atribuição de inteiros"

  -Mensagens de modificações que representam novas funcionalidades ou algo 
   visível/relevante para o usuário devem iniciar com NEW:

     $svn ci A.cpp -m"NEW: estruturas caso/repita agora são suportados"

  -Mensagens que devem ser ignoradas devem iniciar com DEVNULL

     $svn ci A.cpp -m"DEVNULL: identacão de código corrigida"


 Ex 3: Misturando tudo:


    $ svn ci -m"-Função func() renomeada para f()
    > BUGFIX:
    > -Resolvido bug ao depurar arrays de literais
    > -Resolvido bug ao fazer atribuição de inteiros
    > NEW:
    > -Adicionado suporte a estruturas caso/repita
    > -Adicionado suporte a estruturas eterogêneas
    > DEVNULL: 
    > -retirado texto commitado acidentalmente
    > REGULAR:
    > -Adicionado gerador de código para caso/repita"

   No exemplo acima, 2 mensagens são de bugfix, 2 são de novidades,
   1 será ignorada e 2 (a primeira e a última) são mensagens normais.
 
   Portanto, todas as keywords são flags que marcam o texto a seguir em diante.
   REGULAR, portanto, resolve para o default, que são mensagens normais.


  Estas convenções devem ser seguidas para a geração de arquivos ChangeLog
  e NEWS automatizada. ChangeLog reunirá todas as modificações feitas em um 
  período, ignorando mensagens marcadas com DEVNULL, e exibindo mensagens 
  normais e de bugfix. O arquivo NEWS conterá mensagens marcadas com NEW
  e bugfixes.

  Além do mais, BUGFIX pode ser seguido de um número (ie #1234), que representa
169
  o número do bug em um sistema de gerencia de bugs, que no nossa caso é o Mantis.
170 171 172 173 174 175 176 177 178 179 180

o Unit Testing

  -Todo código que pode se beneficiar de testes automatizados *devem* ter testes
  automatizados. Versões de nós mesmos no futuro agradecem.
  
  -Mensagens de commit para arquivos de testes não são tão obrigatórios.
  Use o bom senso para decidir se a descrição do commit ajudaria ou não.
  

  TODO: explicar a infraestrutura de testes (quando houver uma)
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

Documentando
=============

  Os arquivos de documentação ficam no diretório doc.

  O manual está em doc/manual e é escrito em Latex, portanto será necessário a instalação dos seguintes pacotes:
  - latex-make
  - texlive-latex-base
  - latex2html
  
  Os arquivos do manual ficam na pasta doc/manual. E o arquivo principal é o manual.tex.
  Após fazer as modificações, para gerar o pdf, basta executar o comando
  $ latex manual.tex
  
  Para gerar o manual em html, use o comando
  $ latex2html manual.tex

Distribuindo
=============

Para a distribução de uma nova versão do GPT pode-se seguir os seguinte passos:
  
o Atualizar documentação (ver seção Documentando)
  
o Checar se todos os arquivos novos/modificados estão no repositório
  $ svn status 
  
o Testar o versão do SVN em outros ambientes
  
o Mudar a versão no arquivo configure.ac
  Atualizar os paramentros das funções AC_INIT e AM_INIT_AUTOMAKE com a nova versão do gpt
  Após isso executar os comandos, para que a mudança reflita nos arquivos gerados automaticamente:
  $ autoconf && automake
    
o Atualizar NEWS
  O arquivo NEWS deverá ser atualizado manualmente seguindo o padrão utilizado.
    
o Atualizar ChangeLog
  Para gerar o ChangeLog será necessário a instalação do pacote:
  - php-cli
  
  Executar o comando
  $ php stuff/svn2cl.php > ChangeLog
  
o Commit e tag
  Após essas atualizações, deverá ser feito um commit sem comentários e tagear a versão no SVN. 
  $ svn commit
  $ svn copy https://username@svn.berlios.de/svnroot/repos/gpt/trunk/gpt \
            https://username@svn.berlios.de/svnroot/repos/gpt/tags/gpt-1.1\
      -m "Release 1.1"

o Criar pacotes
  - tar.gz
    $ make distclean; mkdir build; cd build; ../configure && make && make distcheck
    
  - debian

o Fazer o upload dos arquivos
  
o Atualizar o site e publicar as novidades