Kochbuch für die Generierung 
  von Device-Access-Software   
  auf dem acc6-Cluster         
================================


I. Hinweise
------------------------------------------

1. Das Kochbuch gilt, solange noch die alte SVN-Struktur
   vorhanden ist.                                       


2. Ich gehe hier davon aus, dass keine neuen Artefakte
   (Projekte) eingebunden, sondern in den bestehenden 
   Artefakten nur Bugs beseitigt oder neue Features 
   eingebaut werden sollen.    


3. Alle Versionen in den POMs (pom.xml) sind Snapshots,
   also z.B. '10.26.02-SNAPSHOT'. Um ein Artefakt ins  
   Nexus zu deployen, muss man also keine Versionsnummer
   in den POMs ändern. Maven fügt einfach einen neuen   
   Schnappschuss hinzu.                                 

   Mit 'deploy' meine ich hier 'mvn deploy' und nicht
   'mvn relase:prepare' und 'mvn relase:perform'!    

   Deploy heißt immer: Etwas ins Nexus-Repository
   hochladen. Siehe auch Anhang B.


4. Nexus findet man unter 'artifacts.acc.gsi.de'. Dann
   (evtl.) 'Repositories' anklicken und 'csco-snapshot'
   auswählen. Alle Artefakte liegen unter              
   'de.gsi.cs.co.fe.devacc'. Zur Zeit (19. Okt. 2015)   
   gilt die Version '10.26.02-SNAPSHOT' für die 
   'framework'-Artefakte bzw. die Version 
   '10.26.03-SNAPSHOT' für die 'hosts'-Artefakte.



II. Subversion
------------------------------------------

1. Den gesamten 'eq-models'-Baum aus SVN aus-checken,
   so dass man ~/<workspace>/eq-models/<eqmodels>    
   vorliegen hat.                                    


2. Alle Device-Access-Framework-Projekte von accdata 
   bis vmedevice aus-checken, so dass man 
   ~/<workspace>/accdata bis ~/<workspace>/vmedevice 
   vorliegen hat (siehe [1]).   


3. Den gesamten 'maven'-Baum aus SVN aus-checken, so
   dass man ~/<workspace>/maven vorliegen hat.      


4. Die Struktur der Verzeichnisse muss genau so sein, weil 
   die meisten 'src'-Verzeichnisse unter 'maven' relative  
   'symbolic links' sind.                                        


5. Das sollte dann z.B. so aussehen:

     workspace/eq-models/bc
                        /...
                        /vvc
              /accdata
              /...
              /vmedevice
              /maven/eqdrivers
                    /eqmodels
                    /fecs
                    /framework
                    /hosts
                    /tests
                    /utilities
                    pom.xml
     


III. Framework
------------------------------------------

1. Bug, bespielsweise in ~/<workspace>/device/xyz.cc,
   beseitigen.                                       


2. Dann im entsprechenden Maven-Verzeichnis

     cd ~/<workspace>/maven/framework/device
     mvn [clean] install

   Siehe auch Anhang B.


3. Für jede Architektur findet man die shared lib in
   .../device/<arch>/target/install/lib/libdevice.so


4. Zum Testen von Anwendungen auf asl73x kann man 
   dann die passende shared lib einfach nach      
   /common/usr/cscofe/opt/devacc/pro/lib[64]      
   kopieren und die Anwendung neu starten.        

   Die Symlinks 'dev' und 'pro' auf 
   /common/usr/cscofe/opt/devacc zeigen zur Zeit 
   noch auf das selbe Ziel (10.26.02-SNAPSHOT).  


5. Den Weg über 

     cd ~/<workspace>/maven/framework/<module>
     mvn [clean] deploy                       

     cd ~/<workspace>/maven/hosts
     mvn [clean] deploy          

     reldevacc [-a i386] 10.26.02

   für x86_64 und i386 empfehle ich im Moment nicht, 
   da man reldevacc zur Zeit noch in der richtigen   
   Reihenfolge aufrufen und zwischen den Aufrufen noch 
   händisch in den Zielverzeichnissen eingreifen muss. 
   (Das geht erst, wenn SCons zwischen lib und lib64   
   unterscheiden kann.)                                

   Einzig für 'python, wenn es also eine Änderung in 
   ~/<workspace>/maven/framework/devacc_python gab,  
   kann man ohne Probleme                            

     reldevacc -a python -s latest 10.26.02

   aufrufen.


6. Sind GuPs betroffen, z.B. über libaccdevice.so,
   dann gibt es zwei Möglichkeiten.               

   a. Zum schnellen Test:

      cd ~/<workspace>/maven/framework/accdevice
      mvn [clean] install                       

      cd ~/<workspace>/maven/fecs/<GuP>
      mvn [clean] install              

      copygup --zipdir=target <GuP> 10.26.00

   b. Ein echtes Rollout:

      cd ~/<workspace>/maven/framework/accdevice
      mvn [clean] deploy                        

      cd ~/<workspace>/maven/fecs/<GuP>
      mvn [clean] deploy               

      relgup -s latest <GuP> 10.26.02


7. Tut Alles wie gewünscht, dann nicht vergessen:

     cd ~/<workspace>/[acc]device
     svn commit -m "Bug <bug> in xyz.cc beseitigt" 

   Und dann den GuP neu starten mit

     ssh root@<GuP>
     reboot        

   Ein Restart des Devman (siehe [2, How a FEC Boots])
   reicht hier nicht, da ja das ZIP-File vom Server   
   (asl73x, benutze 'cdcpu <GuP>') neu geholt werden  
   muss.                                              



IV. Equipment Models
------------------------------------------

Das geht ganz ähnlich wie unter Punkt III.6. 


1. Zunächst Bug, bespielsweise in 
   ~/<workspace>/eq-models/<eqmod>/<eqmod>-device.cc,
   beseitigen.                                       


2. Möchte man tatsächlich eine neue Versionsnummer
   vergeben, dann am einfachsten 

   a. Das pom.xml im Gerätemodell-Mutter-Verzeichnis
      ~/<workspace>/maven/eqmodels/<eqmod> editieren,
      also z.B. hier

        <groupId>de.gsi.cs.co.fe.devacc.eqmodels</groupId>                               
        <artifactId>eqmodel-mx-parent</artifactId>                                       
        <version>10.00.00-SNAPSHOT</version>                                             
        <packaging>pom</packaging>                                                       
       
      von 10.00.00-SNAPSHOT auf 10.00.01-SNAPSHOT
      gehen.

   b. Und im Gerätemodell-Mutter-Verzeichnis 

        mvn -N -DallowSnapshots versions:update-child-modules
        mvn versions:commit

      aufrufen.


3. Dann gibt es wieder die beiden Möglichkeiten.

   a. Zum schnellen Test:

      cd ~/<workspace>/maven/eqmodels/<eqmod>
      mvn [clean] install                    

      cd ~/<workspace>/maven/fecs/<GuP>
      mvn [clean] install              

      copygup --zipdir=target <GuP> 10.26.00

   b. Ein echtes Rollout:

      cd ~/<workspace>/maven/eqmodels/<eqmod>
      mvn [clean] deploy                     

      cd ~/<workspace>/maven/fecs/<GuP>
      mvn [clean] deploy

      relgup -s latest <GuP> 10.26.02

   Zu 'mvn install/deploy' siehe auch Anhang B.


4. Tut Alles wie gewünscht, dann nicht vergessen:

     cd ~/<workspace>/eq-models/<eqmod>
     svn commit -m "Bug <bug> in <eqmod>-device.cc beseitigt" 

   Und den GuP neu starten mit

     ssh root@<GuP>
     reboot        

   Ein Restart des Devman (siehe [2, How a FEC Boots])
   reicht hier nicht, da ja das ZIP-File vom Server   
   (asl73x, benutze 'cdcpu <GuP>') neu geholt werden  
   muss.                                              



V. Equipment Drivers
------------------------------------------

1. Deren Quellen liegen hier direkt unter
   ~/<workspace>/maven/eqdrivers/<drv>/src,
   'src' ist also kein Symlink, sondern ein Directory.


2. Zunächst Bug, bespielsweise in 
   ~/<workspace>/maven/eqdrivers/<drv>/src/xy-drv.cc,
   beseitigen.                                       


3. Dann gibt es wieder die beiden Möglichkeiten.

   a. Zum schnellen Test:

      cd ~/<workspace>/maven/eqdrivers/<drv>
      mvn [clean] install                   

      Und alles weitere wie unter IV.2.a.

   b. Ein echtes Rollout:

      cd ~/<workspace>/maven/eqdrivers/<drv>
      mvn [clean] deploy                    

      Und alles weitere wie unter IV.2.b.


4. Tut Alles wie gewünscht, dann nicht vergessen:

     cd ~/<workspace>/maven/eqdrivers/<drv>/src
     svn commit -m "Bug <bug> in xy-<drv>.cc beseitigt" 

   Und den GuP neu starten wie in IV.3 beschrieben.



VI. Komplette Builds
------------------------------------------

1. Ein komplettes online Build, das die gesamte
   Software baut, geht einfach mit             

     cd ~/<workspace>/maven
     mvn [clean] install   

   Das baut alles in

     eqdrivers,
     eqmodels, 
     fecs,     
     framework,
     hosts,    
     tests und 
     utilities.

   Hinweis am Rande: Maven kann man übrigens in jedem 
   Verzeichnis aufrufen, in dem ein gültiges pom.xml  
   liegt.                                             


2. Jede Nacht checkt Jenkins [3] den ganzen Device-
   Access-Baum aus SVN aus und versucht, die komplette 
   Software zu generieren (nightly build).            

   Hat man neue Quellen in SVN eingecheckt, dann sollte 
   man am nächsten Tag mal nachgucken, ob der Build     
   'fe-devacc-el6' fehlerfrei durchgelaufen ist. Wenn   
   nicht, dann                                          

     'fe-devacc-el6' -> '#<nnn> <Date> <Time> AM' -> 
     'Console Output'                                

   klicken und gucken, wo es geklemmt hat.

   Logged man sich ein (oben rechts), dann kann man auch 
   sofort einen Build-Lauf starten, der dann gut eine    
   halbe Stunde braucht, bis er durch ist.               



VII. Lokale DB-Dateien 
------------------------------------------

1. Diese werden behandelt wie bisher, also

     cd ~/<workspace>/dbd
     dbsgen <GuP>
     dbscopy <GuP>


2. Den GuP neu starten, entweder wie in IV.3 beschrieben
   oder via

     ssh root@<GuP>
     /etc/init/boot.d/99_devman restart    # alte version, bzw.
     /etc/init/boot.d/95_devman restart    # neue version

   Das tut, weil copygup das dbs-File auch auf den remote
   GuP kopiert (mit scp). Man muss hier also nicht den
   kompletten GuP rebooten. Siehe auch [2, How a FEC Boots].



VIII. Conditions (ehem. Messages) 
------------------------------------------

1. Conditions können im Grunde wie bisher behandelt werden.
   Das 'genmsg' aktualisiert direkt die shared Library im
   Produktionsverzeichnis.


2. Da es keine *msg.msg-Dateien mehr gibt, muss man den
   'conditions-loader' benutzen, um Änderungen in der
   Conditions-DB vorzunehmen. Danach erst, wie bisher, das 
   (etwas angepasste) 'genmsg'. Näheres siehe [4].



IX. ECM und EQMs 
------------------------------------------

1. Diese werden mit den gleichen Werkzeugen wie unter acc5 
   generiert.


2. Auch das Laden der Software auf eine SE geschieht 
   weiterhin mit ecload. 

   Der einzige Unterschied ist, dass das ecload auf acc6
   die SR-Datei nur noch direkt runterladen kann und nicht 
   mehr über den Umweg eines gemeinsamen NFS-Verzeichnisses.
   Das auf acc5 bestehende Zeitproblem - das Laden dauerte
   ewig - ist durch eine Neu-Implementierung der DLOAD-
   Property gelöst. 



X. Scripte in utiasl, utivme und utipy
------------------------------------------

1. Bash- und Python-Scripte in ~/workspace/utiasl, 
   ~/workspace/utivme und ~/workspace/utipy werden nach wie 
   vor via Makefile ausgerollt. Das Makefile ist so gebaut, 
   dass es die Scripte auf beide Cluster ausrollt, also auf 
   asl73x und asl33x. 

2. Auf asl73x z.B. einfach

     cd ~/workspace/utiasl
     make copy

   ausführen.



XI. PropHelper und devscr
------------------------------------------

1. Beide werden mit Makefiles released, nicht via Maven.
   Siehe ~/workspave/devscr/devscr/Makefile und
   ~/workspace/PropHelper/src/Makefile.



A. Referenzen
------------------------------------------
[1] Alle notwendigen Device-Access-Framework-Projekte:
    accdata
    accdevice
    alarm
    corbaifc
    cpu87
    dbs
    device
    devicefactory
    devman
    equinf
    incasl
    incvme
    message
    nameserver
    nativedevice
    nsrvclient
    nsrvtcpip
    os
    periservice
    pydevacc
    subscriptionservice
    tools
    ufcserver
    usrs
    vmedevice

[2] https://www-acc.gsi.de/wiki/Frontend/DevaccMavenBuildHowto
[3] https://builder.acc.gsi.de/jenkins/
[4] https://www-acc.gsi.de/wiki/Frontend/DevaccMavenBuildHowto#Create_or_Add_Conditions



B. Maven clean, compile, package, install, deploy
----------------------------------------------------
Was tun, ganz grob, diese Aufrufe?

* mvn clean
  Löscht das 'target'-Directory und dessen Inhalte.
 
* mvn compile
  Kopiert die Quellen nach <arch>/target/build, generiert
  (compile, link, ...) die Software und legt die generierte(n)
  Datei(en) in <arch>/target/install/<subdirs> ab.

* mvn package
  Packt alle Dateien und Directories unter <arch>/target/install
  in eine Zip-Datei und legt sie in <arch>/target ab. Wenn 
  notwendig, wird vorher 'mvn compile' ausgeführt.

* mvn install
  Kopiert die Zip-Datei aus <arch>/target ins lokale Repository
  des Users, entsprechend der <groupId>, der <artifactId> und
  der <version> im pom.xml. Das lokale Repository ist 
  ~/.m2/repository und Device-Access-Software liegt dann in
  der Regel in ~/.m2/repository/de/gsi/cs/co/fe/devacc/...
  Wenn notwendig, wird vorher 'mvn package' ausgeführt.

* mvn deploy
  Kopiert die Zip-Datei aus dem lokalen Repository des Users 
  ins globale Nexus-Repository (upload), entsprechend der 
  <groupId>, der <artifactId> und der <version> im pom.xml. 
  Ist die <version> im pom.xml eine SNAPSHOT-Version, dann 
  landet die Zip-Datei in 'csco-snapshot', ansonsten in 'csco'. 
  Wenn notwendig, wird vorher 'mvn install' ausgeführt.

Ist man weiter oben im Verzeichnisbaum, dann werden die 
Aktionen für jedes darunterliegende Modul ausgeführt.