CSMake – Manual do Usuário

André Costa
$Id: csmake-manual.html 34494 2004-08-24 17:41:51Z costa $

Introdução
Conceitos Básicos
Script de bootstrap
Arquivo de configuração
Prefixo do projeto
Algoritmos
Configuração Local
Redefinindo acesso ao CVS
Evitando compilação de módulos especíificos
Comandos e parâmetros
"comando nulo"
obtendo informações sobre a execução
co (checkout)
update
compare
tag
build
class
clean
doc
alg
servers
run
props
Exemplo de Uso
Primeiro projeto: InfoPAEd
Segundo Projeto: WebSintesi

Introdução

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 é:

Conceitos Básicos

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.

Script de bootstrap

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:

Arquivo de Configuração

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/

Prefixo do projeto

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

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.

Configuração Local

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.

Redefinindo acesso ao CVS

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"

Evitando compilação de módulos específicos

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

Comandos e Parâmetros

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

Dependências e Requisitos

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.

Comandos

“comando nulo”

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

Obtendo informações sobre a execução

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'.

co (checkout)

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)

update

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

compare

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

tag

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

build

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

class

Compila apenas um único arquivo .java.

Parâmetros

arq

arquivo a ser compilado. Pode ser especificado via path absoluto ou relativo

clean

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.

doc

Gera documentação. Executa o comando make doc.

Parâmetros

[m1 m2 ...]

módulos afetados pela operação

-n

apenas simula execução

alg (algoritmos)

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

servers

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

run

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

props

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/

Relaxando restrições: o parâmetro global '-f'

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

Exemplo de uso

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

Primeiro projeto: InfoPAEd

checkout do projeto

~ 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

recuperação dos demais módulos

~/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

usando o csmake

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

Segundo Projeto: WebSintesi

À 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.

checkout do projeto

~/trab/websintesi cvs -d /home/t/tecgraf/prod/app/websintesi/CVS co src
[...]

recuperação dos demais módulos

~/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