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
|
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
o número do bug em um sistema de gerencia de bugs, que no nossa caso é o Mantis.
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)
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
|
