André Costa
$Id: csmake-manual.html 34494 2004-08-24 17:41:51Z costa $
O CSMake consiste de um conjunto de scripts Lua e bourne-shell criados para facilitar o desenvolvimento de projetos baseados no CSBase (InfoPAEd, WebSintesi). Mais especificamente, seu principal objetivo é:
tornar obsoletas as inúmeras ferramentas e procedimentos hoje utilizados nas diferentes etapas do desenvolvimento (build, configure, make –just-compile etc.). Cada etapa atualmente depende de scripts e parâmetros próprios, sem que haja padronização.
oferecer uma interface única para todas as tarefas associadas à manutenção e desenvolvimento dos diferentes módulos que compõem os projetos
facilitar as operações relativas aos módulos que compõem os projetos a partir de um ponto central
padronizar e automatizar o procedimento de deployment dos projetos1
portabilidade (deve funcionar em ambientes heterogêneos)
facilitar o desenvolvimento e deployment em ambientes heterogêneos, aonde etapas específicas só podem ser executadas em determinados nós
O csmake, como o nome indica, é parte do projeto CSBase. Cada projeto baseado no CSBase possui um script de bootstrap e um arquivo de configuração.
O script de bootstrap é executado localmente, na árvore de cada projeto, e consiste essencialmente de um wrapper para o script principal, localizado dentro do módulo csbase. Basicamente ele opera da seguinte forma:
caso não exista um diretório ../csbase, este será recuperado do CVS ou aproveitado de outro projeto (via link simbólico). O usuário é guiado interativamente por estas opções. Esta etapa é tipicamente realizada apenas uma vez, durante a configuração inicial do projeto
caso contrário, simplesmente repassa os parâmetros para o “verdadeiro” script
A estrutura de módulos do CVS que compõem o projeto é descrita através da sintaxe de Lua no arquivo de configuração csmake.cfg. Por exemplo a descrição do projeto InfoPAEd é:
TAG_PREFIX = "ID" WEBSINTESI_CVS = "/home/t/tecgraf/prod/app/websintesi/CVS" INFOPAED_CVS = "/home/t/tecgraf/prod/app/infopaed/CVS" CSBASE_CVS = "/home/t/tecgraf/prod/app/csbase/CVS" installTree { { rep = CSBASE_CVS, module = "csbase" }, { rep = INFOPAED_CVS, module = "infopaed", { rep = INFOPAED_CVS, module = "x-apps" }, { rep = INFOPAED_CVS, module = "algorithms", isAlgorithm = true }, }, { rep = WEBSINTESI_CVS, module = "sgad" }, { rep = INFOPAED_CVS, module = "install" }, { rep = INFOPAED_CVS, module = "init" }, }
Cada elemento no formato
{ rep = CSBASE_CVS, module = "csbase" },
corresponde a um módulo do CVS, cujo nome é indicado pelo campo module, e repositório indicado pelo campo rep. Módulos podem conter referências para outros módulos (como é o caso de infopaed no exemplo acima).
O arquivo acima recupera os módulos do CVS de acordo com a seguinte estrutura de diretórios:
csbase/ infopaed/ infopaed/x-apps infopaed/algorithms init/ install/ sgad/
A variável TAG_PREFIX define o prefixo do projeto, usado na definição de defaults para as tags (vide comando tag).
Os valores típicos são prefixos de 2 letras (p.ex. ID para o InfoPAEd e WS para o WebSintesi)
Algoritmos têm papel especial, e portanto possuem operações e tratamento específicos. Para que o csmake possa identificar o nó da árvore que contém os algoritmos, este deve deve ser identificado através do atributo isAlgorithm, associando-se a este o valor true. Toda árvore deve possuir um e somente um nó com isAlgorithm = true.
Existem determinadas situações em que é necessário uma configuração local diferente do default; um caso típico é o uso a partir da PETROBRAS, aonde o acesso ao CVS deve ser feito via ssh.
Para permitir configurações locais, o csmake carrega um arquivo de nome local.cfg caso este exista no diretório principal do projeto.
Para se permitir acesso remoto via ssh ao CVS do Tecgraf, as seguintes redefinições poderiam ser definidas no local.cfg:
WEBSINTESI_CVS = ":ext:seulogin@ssh.tecgraf.puc-rio.br:/home/t/tecgraf/prod/app/websintesi/CVS" INFOPAED_CVS = ":ext:seulogin@ssh.tecgraf.puc-rio.br:home/t/tecgraf/prod/app/infopaed/CVS" CSBASE_CVS = ":ext:seulogin@ssh.tecgraf.puc-rio.br:/home/t/tecgraf/prod/app/csbase/CVS"
Em alguns casos, a compilação de determinados módulos é desnecessária (ou mesmo indesejada); o WIO é um exemplo típico. O csmake permite que módulos sejam ignorados (apenas para a operação de build) através da variável BUILD_IGNORE.
Por exemplo, se local.cfg contém a seguinte definição:
BUILD_IGNORE = { "init", "x-apps" }
o resultado de um build de todos os módulos resulta em:
./csmake build [INFO] carregando definicoes locais (./local.cfg) [WARN] ignorando modulo >>> init [WARN] ignorando modulo >>> x-apps [INFO] atualizando modulo >>> install (... segue com a compilação dos demais módulos)
Observações
os nomes dos módulos correspondem aos definidos no arquivo csmake.cfg
módulos listados em BUILD_IGNORE nunca serão compilados, mesmo que sejam referenciados nominalmente na linha de comando
O csmake opera através de comandos (ou ações), que por sua vez podem ser customizados através de parâmetros. Existem alguns parâmetros globais (i.e. que afetam todos os comandos) e parâmetros específicos para cada comando. Sempre que possível, procurou-se utilizar parâmetros que tivessem paralelo com situações típicas do desenvolvimento (p.ex. parâmetros do CVS).
Comandos são strings, parâmetros são sempre letras (maiúsculas ou minúsculas) precedidas por hífen.
Observações
todo comando que recebe como parâmetros nomes de módulos atuará por default sobre todos os módulos caso nenhum seja especificado.
todos os comandos são executados a partir do diretório principal do projeto, independente do(s) módulo(s) a que se refira
a ordem dos parâmetros é irrelevante. csmake build -v -l equivale por exemplo a csmake -l build -v
Existem dependências implícitas entre alguns comandos, de forma a tentar garantir que a operação solicitada possa ser efetuada. Por exemplo, virtualmente todos os comandos dependem do comando co (checkout), que garante que a estrutura de diretórios foi criada de forma apropriada.
Além das dependências entre comandos, existem também requisitos que devem ser satisfeitos para que alguns comandos possam ser executados. Tipicamente, requisitos estão relacionados a aplicativos instalados no sistema. Por exemplo, a ação de checkout depende do comando cvs e do ssh; build depende da existência do GNU make e de alguma versão do compilador javac etc.
Ao executar pela primeira vez em uma determinada máquina, o csmake identifica as versões dos aplicativos pertinentes instalados na mesma, e os armazena em um arquivo para futura referência. Desta forma, é possível, caso um requisito não possa ser satisfeito na máquina corrente, sugerir outra máquina que possa desempenhar a tarefa solicitada (caso essa outra máquina conste do “banco de dados”). 2
Requisitos são atualmente especificados diretamente no código do csmake, se houver necessidade não será complicado implementar um esquema mais flexível.
Via de regra, ao menos uma ação deve ser especificada:
./csmake [WARN] nenhuma acao foi especificada. Use o parametro '-h' para ajuda
A única exceção para esta regra é a obtenção de ajuda através do parâmetro -h :
~ ./csmake -h Acoes: ---------- doc : gera documentacao co : traz arvore de diretorios do CVS (checkout) servers : exibe informacoes dos servidores class : compila um unico arquivo update : atualiza arvore local compare : compara fontes com o CVS clean : remove binarios tag : aplica/remove tags simbolicas alg : operacoes sobre algoritmos build : compila o codigo run : execucao de aplicacoes/componentes Parametros globais: ---------- -v : verbose mode -f : forca execucao mesmo que requisitos de versoes nao sejam atendidos -h : este texto [*] [*] o parametro -h pode ser utilizado juntamente com um comando para se obter ajuda apenas para o mesmo. Ex.: csmake -h build
Como o texto acima indica, pode-se usar o parâmetro -h para se obter ajuda com relação a um comando específico:
~ ./csmake -h build Build: ---------- [m1 m2 ...] : modulos afetados pela operacao [*] -l : gera versao local (nao faz update) -n : apenas simula execucao [*] caso nao sejam especificados modulos, atua sobre TODOS os modulos OBS.: por default os fontes sao atualizados (cvs update) antes da compilacao
Além do parâmetro -h, existe outro parâmetro global (-v) que tem como propósito visualizar informações detalhadas sobre a execução dos comandos:
./csmake -v build init [DEBUG] verificando versao: ssh (*) [DEBUG] verificando versao: cvs (*) [DEBUG] verificando status de Checkout [DEBUG] verificando ../csbase [DEBUG] verificando ../infopaed [DEBUG] verificando ../infopaed/x-apps [DEBUG] verificando ../infopaed/algorithms [DEBUG] verificando ../sgad [DEBUG] verificando ../install [DEBUG] verificando ../init [DEBUG] verificando versao: make (GNU) [DEBUG] verificando versao: javac (1.4.2) [DEBUG] executando acao: build [DEBUG] executando acao: cvs update [INFO] atualizando modulo >>> init [DEBUG] (cd ../init; cvs -q update -P -d 2>&1) === CONFLITOS [C] : 0 === Modificados [M] : 0 === Novos [U] : 0 === Atualizados [P] : 0 === Adicionados [A] : 0 === Removidos [R] : 0 === Locais [?] : 0 [INFO] gerando modulo >>> init [DEBUG] (cd ../init; gmake ) gmake: Nothing to be done for `init'.
Recupera a árvore do projeto, de acordo com o especificado no arquivo csmake.cfg. Apenas os módulos ausentes são recuperados.
Parâmetros
-r dir |
especifica diretório-raiz para checkout [../] |
-d cvsroot |
especifica repositório no CVS (ex.: :ext:user@server:path) |
Atualiza o código-fonte de um ou mais módulos.
Parâmetros
[m1 m2 ...] |
módulos afetados pela operação |
-n |
apenas simula execução |
-C |
descarta arquivos locais ("clean copy"). Os arquivos modificados localmente são renomeados para .#nome-do-arquivo.X.Y, aonde X.Y corresponde à versão local que seria sobrescrita |
-s |
exibe apenas estatísticas |
-A |
recupera última versão (HEAD) dos fontes do CVS |
-r tag |
recupera os fontes associados a tag |
Os resultados são exibidos de forma semelhante aos exibidos pelo comando tecvs mods:
[INFO] atualizando modulo >>> infopaed === CONFLITOS [C] : 0 === Modificados [M] : 0 === Novos [U] : 2 U runserver U runserver.bat === Atualizados [P] : 0 === Adicionados [A] : 0 === Removidos [R] : 0 === Locais [?] : 0
O flag entre colchetes corresponde ao retornado pelo CVS. Normalmente, os arquivos que se enquadram nas respectivas categorias são exibidos logo após as mesmas, como os dois arquivos novos no exemplo acima. O parâmetro -s, porém, faz com que apenas os resumos sejam exibidos, ou seja, o exemplo acima ficaria:
[INFO] atualizando modulo >>> infopaed === CONFLITOS [C] : 0 === Modificados [M] : 0 === Novos [U] : 2 === Atualizados [P] : 0 === Adicionados [A] : 0 === Removidos [R] : 0 === Locais [?] : 0
Conflitos merecem especial atenção, a tal ponto que quando acontecem o csmake suspende a execução avisando do problema, antes de exibir os respectivos arquivos.
Observações
mesmo com o parâmetro -s, conflitos são sempre exibidos
Equivale ao tecvs mods; idêntico ao comando csmake update -n.
Parâmetros
[m1 m2 ...] |
módulos afetados pela operação |
-s |
exibe apenas estatísticas |
Associa ou remove uma tag de todo o projeto, ou de módulos específicos.
Parâmetros
[m1 m2 ...] |
tag a ser aplicada e módulos afetados pela operação |
-n |
apenas simula execução |
-d tag |
remove a tag |
-L |
lista as tags existentes para o projeto |
Observações
a tag é obtida de forma interativa
será sugerida uma tag default de acordo com o padrão XX-YYYY-MM-DD, aonde XX = prefixo do projeto (definido por TAG_PREFIX) e YYYY-MM-DD corresponde à data atual
Compila o código-fonte. Opcionalmente, pode também desempenhar outras tarefas – o comando build na verdade executa o make nos respectivos diretórios; portanto, todas as tarefas normalmente associadas aos builds serão também executadas.
Parâmetros
[m1 m2 ...] |
módulos afetados pela operação |
-l |
gera versão local (não faz update) |
-n |
apenas simula execução |
Observações
a compilação de múltiplos módulos é interrompida caso algum passo resulte em erro.
a lista dos módulos que serão compilados é afetada pela variável BUILD_IGNORE
Compila apenas um único arquivo .java.
Parâmetros
arq |
arquivo a ser compilado. Pode ser especificado via path absoluto ou relativo |
Remove arquivos binários resultantes das compilações. É a contraparte ao comando build.
Parâmetros
[m1 m2 ...] |
módulos afetados pela operação |
-n |
apenas simula execução |
De forma análoga ao comando build, clean também depende da existência de um makefile devidamente configurado.
Gera documentação. Executa o comando make doc.
Parâmetros
[m1 m2 ...] |
módulos afetados pela operação |
-n |
apenas simula execução |
Devido a características próprias tais como a existência de inúmeras versões, algoritmos merecem tratamento especial. De uma forma geral, opções disponíveis normalmente como comandos (build, tag, clean etc.) não têm efeito sobre algoritmos; elas estão disponíveis apenas através de parâmetros específicos ao comando alg:
Parâmetros
[a1 a2...] |
algoritmos a serem manipulados; caso nenhum seja especificado, todos serão afetados. Estes valores não são considerados se fornecidos juntamente com o parâmetro -t (vide abaixo) |
-V |
versão do algoritmo a ser manipulada; apenas uma versão pode ser especificada por vez |
-l |
gera versão local (não faz update) |
-L |
lista algoritmos disponíveis e suas respectivas versões |
-b |
gera algoritmos (build) |
-C |
remove binários (clean) |
-t tag |
aplica tag a todos os algoritmos |
-n |
apenas simula execução |
Conforme mencionado acima, diferentes tarefas realizadas pelo csmake têm diferentes pré-requisitos. Em ambientes heterogêneos (como por exemplo a PETROBRAS), nem todos os servidores envolvidos no processo de desenvolvimento necessariamente preenchem todos os pré-requisitos.
De forma a facilitar o processo de identificação dos servidores aptos a executar determinadas tarefas, o csmake coleta e armazena a lista de aplicações disponíveis em cada servidor. O acesso a esta lista é controlado pelo comando servers:
Parâmetros
(vazio) |
lista todas as informações coletadas |
-u |
atualiza informações do servidor corrente |
-R |
reinicializa a lista, removendo todas as informações e atualizando apenas os dados relativos ao servidor corrente |
Exemplo:
./csmake servers dali ----- ssh OpenSSH_3.6.1p2 javac 1.4.2 os Linux cvs 1.11.17 osver 2.4.26-SMP make GNU 3.79.1 java 1.4.2_05 sargent ----- ssh OpenSSH_3.6.1p2 javac 1.4.2_05 os Linux cvs 1.11.17 osver 2.4.22-1.2188.nptlsmp make GNU 3.79.1 java 1.4.2_05
Quando um requisito não é satisfeito, os servidores capazes de fazê-lo são listados, para que o desenvolvedor saiba aonde a tarefa pode ser executada.
Por exemplo:
./csmake build init [WARN] 'javac' nao disponivel [WARN] o executavel pode ser encontrado nos seguintes servidores: dali 1.4.2
A verificação de dependências é feita também com relação às versões instaladas. Por exemplo:
./csmake build init [FATAL] 'javac' : versao incompativel versao esperada: 1.4.2 versao encontrada: 1.4.1 [INFO] o executavel pode ser encontrado nos seguintes servidores: dali 1.4.2
Observações
Para que os testes com o cliente e o servidor possam ser realizados, o csmake disponibiliza o comando run. Através dele, as aplicações são executadas em janelas próprias, criadas exclusivamente para este fim, de forma a não ocupar o terminal aonde é executado o csmake.
Apenas algumas aplicações estão cadastradas para execução via run; a lista pode ser obtida através do help do próprio comando:
Run: ---------- app [p1 p2 ...] : aplicacao/componente a ser executado Aplicacoes disponiveis e seus respectivos parametros: client servidor:porta server
Parâmetros
app [p1 p2...] |
aplicação a ser executada, com seus respectivos parâmetros |
Observações
os parâmetros são simplesmente repassados à aplicação, sem nenhuma verificação quanto à forma ou o conteúdo dos mesmos; o run apenas verifica se o número de parâmetros satisfaz o mínimo exigido por esta
Uma questão que merece especial atenção após o checkout inicial é a correta configuração dos properties.
Para auxiliar na identificação destes valores, o comando props exibe os valores das propriedades relevantes. P.ex.:
./csmake props * URL do repositorio de algoritmos [ AlgorithmService.properties ] RepositoryBaseURL = http://websintesi.ep.petrobras.com.br:8080/initservice/algorithms/ * servidor HTTP [ HttpService.properties ] httpserver = http://websintesi.ep.petrobras.com.br:8080/ * parametros de acesso ao BD de informacoes de interpretacao [ InterpretationDBService.properties ] InterpretationDBService.db = jdbc:oracle:thin:@164.85.9.202:1521:sismica * servidor de login (autenticacao via Windows) [ LoginService.properties ] loginServer = millet:8450 * servidor de email [ MailService.properties ] mail.smtp.host = epln01.ep.petrobras.com.br [...]
O comando aceita apenas um único parâmetro (opcional), que definirá um filtro a ser aplicado sobre a saída. A filtragem não distingue minúsculas de músculas. P.ex.:
./csmake props http [INFO] filtrando por 'http' * URL do repositorio de algoritmos [ AlgorithmService.properties ] RepositoryBaseURL = http://websintesi.ep.petrobras.com.br:8080/initservice/algorithms/ * servidor HTTP [ HttpService.properties ] httpserver = http://websintesi.ep.petrobras.com.br:8080/ * servidor HTTP para imagens [ VGEService.properties ] VGEService.httpImagesServer = http://websintesi.ep.petrobras.com.br:8080/initservice/vge/
Em ambos os exemplos anteriores, os erros de pré-requisitos implicariam no término da execução do csmake. Existe porém uma forma de se relaxar o mecanismo de pré-requisitos, de forma que a execução possa ser forçada (apesar de, muito provavelmente, isto vir a resultar em erros). Isto é conseguido através do parâmetro -f.
Por exemplo, sem o parâmetro teríamos em um caso hipotético:
./csmake build init [FATAL] 'java' : versao incompativel versao esperada: 1.4.1 versao encontrada: 1.3.1 [INFO] o executavel pode ser encontrado nos seguintes servidores: ryder 1.4.1_02 gris 1.4.2_05 sargent 1.4.2_05
O mesmo exemplo acima, com o parâmetro, resultaria em:
./csmake build init -f [FATAL] 'java' : versao incompativel versao esperada: 1.4.1 versao encontrada: 1.3.1 [INFO] o executavel pode ser encontrado nos seguintes servidores: ryder 1.4.1_02 gris 1.4.2_05 sargent 1.4.2_05 [WARN] ignorando falhas de requisitos [INFO] atualizando modulo >>> init === CONFLITOS [C] : 0 === Modificados [M] : 0 === Novos [U] : 0 === Atualizados [P] : 0 === Adicionados [A] : 0 === Removidos [R] : 0 === Locais [?] : 0
Observações
Esta seção descreve passo-a-passo como usar o csmake em um dos projetos suportados (InfoPAEd, WebSintesi). Em seguida, será descrito como configurar o uso do csmake em dois projetos simultaneamente, com compartilhamento do csbase via link simbólico.
Ao longo deste exemplo, assumiremos que o diretório aonde serão extraídos os projetos é ~/trab, e que os repositórios do CVS para os projetos são:
InfoPAEd |
/home/t/tecgraf/prod/app/infopaed/CVS |
WebSintesi |
/home/t/tecgraf/prod/app/websintesi/CVS |
~ cd ~/trab; cvs -d /home/t/tecgraf/prod/app/infopaed/CVS co infopaed [...] ~/trab ls -l total 4 drwxr-xr-x 8 costa tecgraf 4096 Jul 30 10:48 infopaed/ ~/trab ls -l infopaed/csmake* -rwxr-xr-x 1 costa tecgraf 2006 Jul 29 07:45 infopaed/csmake* -rw-r--r-- 1 costa tecgraf 563 Jul 26 19:25 infopaed/csmake.cfg
~/trab cd infopaed/ dali ~/trab/infopaed ./csmake co E necessaria a existencia de um diretorio '../csbase'. Opcionalmente, ../csbase pode ser um link para um diretorio ja existente, utilizado por outro projeto. Deseja criar um link para um diretorio ja existente? (s/N)
No nosso caso, digitamos “n” ou simplesmente ENTER (“n” é o default).
* Prosseguindo com checkout Entre com o repositorio do cvs para o modulo 'csbase' [default = /home/t/tecgraf/prod/app/infopaed/CVS] > /home/t/tecgraf/prod/app/csbase/CVS [WARN] Fazendo checkout de 'csbase' em .. Confirma? (S/n)
Novamente, o default é adequado.
O csmake fez o checkout do csbase no diretório ../, e em seguida de todos os demais módulos descritos no csmake.cfg, em seus respectivos lugares. Como resultado, os seguintes módulos foram extraídos:
~/trab/csbase ~/trab/init ~/trab/install ~/trab/sgad ~/trab/infopaed ~/trab/infopaed/x-apps ~/trab/infopaed/algorithms
Dado que os checkouts foram realizados, o csmake encontra-se disponível para uso. A única restrição é que ele deve sempre ser executado a partir do diretório principal do projeto (no caso, infopaed):
~/trab/infopaed ./csmake -h build Build: ---------- [m1 m2 ...] : modulos afetados pela operacao [*] -l : gera versao local (nao faz update) -n : apenas simula execucao [*] caso nao sejam especificados modulos, atua sobre TODOS os modulos OBS.: por default os fontes sao atualizados (cvs update) antes da compilacao
À primeira vista, o WebSintesi poderia ser extraído no mesmo diretório que o InfoPAEd. Do ponto de vista de reaproveitamento do csbase isto faz sentido (e seria adequadamente gerenciado pelo csmake); porém, ambos os projetos possuem módulos diferentes init e install, o que causaria problemas.
Até que os projetos sejam reestruturados, não há alternativa viável a não ser extrair o WebSintesi em outro diretório e compartilhar o csbase via link simbólico.
Criaremos portanto o diretório ~/trab/websintesi, aonde extrairemos o módulo src.
~/trab/websintesi cvs -d /home/t/tecgraf/prod/app/websintesi/CVS co src [...]
~/trab/websintesi cd src ~/trab/websintesi/src ./csmake co E necessaria a existencia de um diretorio '../csbase'. Opcionalmente, ../csbase pode ser um link para um diretorio ja existente, utilizado por outro projeto. Deseja criar um link para um diretorio ja existente? (s/N) s
Observar que desta vez devemos informar que deve ser feito um link para um csbase já existente.
* Prosseguindo com link Entre com o path ABSOLUTO para o diretorio 'csbase' ja existente (~ = $HOME) > ~/trab/csbase [INFO] modulo csbase ja recuperado [INFO] modulo src ja recuperado [INFO] diretorio: ../src/ modulo: x-apps [...] ~/trab/websintesi/src ls -l .. lrwxrwxrwx 1 costa tecgraf 25 Jul 30 11:23 csbase -> /home/j/costa/trab/csbase/ drwxr-xr-x 25 costa tecgraf 4096 Jul 30 11:24 src/
Todos os módulos foram devidamente extraídos, e a estrutura do projeto WebSintesi agora é:
~/trab/websintesi/csbase@ ~/trab/websintesi/init ~/trab/websintesi/install ~/trab/websintesi/src ~/trab/websintesi/src/algorithms ~/trab/websintesi/src/x-apps ~/trab/websintesi/wio
De forma análoga ao InfoPAEd, o csmake deve ser executado sempre a partir do diretório ~/trab/websintesi/src.
1previsto para a fase II
2futuramente o csmake pode até mesmo vir a executar remotamente comandos de forma a satisfazer requisitos, se isto for viável