Organize ROOT Analyses with Autoconf

Why? Macro to Program Class Structure Analysis Software Links
1 Why?
2 Macro to Program
3 Class Structure
4 Analysis Software
5 Links
Using Automake & Doxygen
for setting up your Analysis Software
A Step-by-Step Guide using ROOT’s hSimple.C tutorial
Patrick Huck
Juniors Day @ STAR Collab. Meeting, LBNL
(11/14/2011)
1 / 29
Juniors Day @ STAR Collaboration Meeting LBNL (11/14/2011)
Patrick Huck

View Slide

Requirements
– easy to keep tidy
– compiled programs
- fast fitting & looping
- detect bugs during compilation not runtime
- controlled by main program
– I/O controlled by program invocation
- options/parameters
- no recompilation, no hard-coding
– easily include foreign classes/code
– Utility/Database classes
– GNU standard
- configure, make [clean, distclean, dist]
- platform independent
– documentation within code
- man-pages, L
A
TEX
- Analysis Homepage
– simplified Makefiles
– one ’make’ generates all
automake
&
doxygen
with a little effort these two in
combination make all this possible.
This talk goes through an easy
example to illustrate the setup and
usage of automake incl. doxygen.
Links and files will soon be provided.
2 / 29
Patrick Huck

View Slide

General Structure Documentation (HTML/man) L
ATEXDoc. and Distribution Package
MySimpleExample/
README
configure.ac
Makefile.am
src/
hSimple.cc
bin/
hSimple
out/
hsimple.root
pics/
hSimple.png
config/
– README file for instructions
– configuration file for ./configure
01: AC INIT([My Simple Example], [11.11.14], [[email protected]], [MySimpleEx-
ample], [http://www.star.bnl.gov/protected/lfspectra/huck/])
02: AC PREREQ(2.59)
03: AM SILENT RULES([yes])
04: AC CONFIG AUX DIR(config)
05: AM INIT AUTOMAKE([-Wall no-define])
06: AC PROG CC
07: AC PROG CXX
08: ROOT PATH
09: AM PROG LIBTOOL
10: AC SUBST(DEPS CFLAGS)
11: AC SUBST(DEPS LIBS)
17: AC CONFIG FILES([Makefile])
18: AC OUTPUT
– main program for $ROOTSYS/tutorials/hsimple.C
– simple Makefile for generating bin/hSimple
– generate all (program installed in bin/)
– add MySimpleExample/bin to $PATH in ~/.bashrc
– run the program specifying the output file
3 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
hSimple.cc
bin/
hSimple
out/
hsimple.root
pics/
hSimple.png
config/
058: void *hsimple(TFile* hfile) { // hSimple.C code
106: int main(int argc, char **argv) {
107: TRint* theApp = new TRint("App", &argc, argv, NULL, 0);
108: if ( theApp->Argc() == 2 ) {
109: TString filename = theApp->Argv(1);
110: TFile* hfile = new TFile(filename,"RECREATE");
111: hsimple(hfile);
112: }
117: theApp->Run();
118: return 0;
119: }
4 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
hSimple.cc
bin/
hSimple
out/
hsimple.root
pics/
hSimple.png
config/
02: # General Stuﬀ
03: AUTOMAKE OPTIONS = subdir-objects foreign
04: ACLOCAL AMFLAGS = -I /Applications/root/build/misc
05: AM CPPFLAGS = $(DEPS CFLAGS) -I$(ROOTINCDIR)
06: AM CFLAGS = $(LAYOUT CFLAGS)
09: # hSimple program
10: bin PROGRAMS = bin/hSimple
11: bin hSimple SOURCES = src/hSimple.cc
12: bin hSimple CXXFLAGS = @[email protected]
13: bin hSimple LDADD = [email protected]@ @[email protected]
@[email protected] @[email protected] ${DEPS LIBS}
5 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
hSimple.cc
bin/
hSimple
out/
hsimple.root
pics/
hSimple.png
config/
1: autoreconf -v --force --install
2: ./conﬁgure
3: make
6 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
hSimple.cc
bin/
hSimple
out/
hsimple.root
pics/
hSimple.png
config/
1: export PATH=$PATH:[your/top srcdir]/bin
1: hSimple "out/hsimple.root"
7 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
mainpage.cc
hSimple.cc
bin/
docs/
Doxyfile.in
html/
index.html
...
man/man3/
hSimple.3
out/
pics/
config/
– add doxygen support to configure.ac
12: AC CHECK PROGS([DOXYGEN], [doxygen])
13: if test -z "$DOXYGEN";
14: then AC MSG WARN([Doxygen not found - continuing w/o support])
15: fi
16: AM CONDITIONAL([HAVE DOXYGEN],[test -n "$DOXYGEN"])
AM COND IF([HAVE DOXYGEN], [AC CONFIG FILES([docs/Doxyfile])])
– add doxygen support to Makefile.am
21: # doxygen
22: if HAVE DOXYGEN
23: all-local:
27: $(DOXYGEN) docs/Doxyfile
30: endif
– modify docs/Doxyfile.in
– add comments at top of src/hSimple.cc
– generate html start page: src/mainpage.cc
– html-documentation automatically generated
– man-pages automatically generated
8 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
mainpage.cc
hSimple.cc
bin/
docs/
Doxyfile.in
html/
index.html
...
man/man3/
hSimple.3
out/
pics/
config/
– add doxygen support to configure.ac and Makefile.am
(html, man and latex generation set to YES)
002: PROJECT NAME = "title"
003: PROJECT NUMBER = 11.11.14
004: PROJECT BRIEF = "subtitle"
005: PROJECT LOGO = [absolute url to logo]
006: OUTPUT DIRECTORY = [absolute url to docs/]
099: INPUT = [absolute url to src/]
142: IMAGE PATH = [absolute url to pics/]
176: HTML EXTRA FILES = [absolute url to pics/]
9 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
mainpage.cc
hSimple.cc
bin/
docs/
Doxyfile.in
html/
index.html
...
man/man3/
hSimple.3
out/
pics/
config/
001: /*!
003: * \class hSimple
004: *
005: * \brief program for hsimple ROOT tutorial
006: *
007: * program description
011: *
017: * \par Steps in Detail (see presentation ... url)
018: * \li mk folders: src,docs,bin,pics,out
027: *
028: * \par Images
029: * \image html ”pics/hSimple.png” ”px distribution”
030: * \image latex ”pics/hSimple.png” ”px distribution” width=10cm
031: *
032: * \par Usage
033: * hSimple filename
034: * \param[in] filename filename (incl. dir) for output file
036: */
10 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
mainpage.cc
hSimple.cc
bin/
docs/
Doxyfile.in
html/
index.html
...
man/man3/
hSimple.3
out/
pics/
config/
01: /*!
03: * \mainpage Start Page
04: *
05: * \note \b Update (Sep 19 2011)

06: * \li performed and added class for basic RefMult QA (refMultQA)
10: *
11: * \par Table of Contents
12: * The following list outlines the order of programs used for my analysis.\n
13: * The links lead to the respective documentation.
14: * \li hSimple
16: */
11 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
mainpage.cc
hSimple.cc
bin/
docs/
Doxyfile.in
html/
index.html
...
man/man3/
hSimple.3
out/
pics/
config/
– html-documentation automatically generated into
docs/html/ during make (start page, links, source code)
12 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
mainpage.cc
hSimple.cc
bin/
docs/
Doxyfile.in
html/
index.html
...
man/man3/
hSimple.3
out/
pics/
config/
13 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
mainpage.cc
hSimple.cc
bin/
docs/
Doxyfile.in
html/
index.html
...
man/man3/
hSimple.3
out/
pics/
config/
14 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
mainpage.cc
hSimple.cc
bin/
docs/
Doxyfile.in
html/
index.html
...
man/man3/
hSimple.3
out/
pics/
config/
– man-pages automatically generated into docs/man
→ include docs/man/ in $MANPATH to use via man hSimple
15 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
bin/
docs/
Makefile mod
refman mod.tex
update texfile.sh
html/
latex/
refman mod.tex
Makefile mod
doxygen.sty
main.tex
classh simple.tex
man/
out/
pics/
config/
MySimpleExample-11.11.14.tar.gz
– L
A
TEX-ﬁles generated by doxygen during make
→ doxygen.sty, main.tex, classh simple.tex, ...
→ docs/html/ re-generated
21: # doxygen
22: if HAVE DOXYGEN
23: all-local:
24: rm -rf $(top srcdir)/docs/html
25: mkdir docs/html
26: # ./bin/copy ﬁles.sh # copy pics included w/ tag
30: endif
– include latex mod’s in all-local target in Makefile.am
– generate pdf-documentation
– control distribution package
– generate tar ball for code sharing/distribution
16 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
bin/
docs/
Makefile mod
refman mod.tex
update texfile.sh
html/
latex/
refman mod.tex
Makefile mod
doxygen.sty
main.tex
classh simple.tex
man/
out/
pics/
config/
– L
A
21: # doxygen
22: if HAVE DOXYGEN
23: all-local:
24: rm -rf $(top srcdir)/docs/html
25: mkdir docs/html
26: # ./bin/copy files.sh # copy pics included w/ tag
28: cp docs/refman mod.tex docs/latex/
29: cp docs/Makefile mod docs/latex/
30: endif
i) docs/refman_mod.tex includes only necessary
tex-files in documentation section (change author
and modify when new class/program is generated)
ii) docs/update_texfile.sh updates the title page
in docs/refman_mod.tex (no mod’s needed)
iii) docs/Makefile_mod calls update_texfile.sh
when the pdf-file is generated (no mod’s needed)
17 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
bin/
docs/
Makefile mod
refman mod.tex
update texfile.sh
html/
latex/
refman mod.tex
Makefile mod
doxygen.sty
main.tex
classh simple.tex
man/
out/
pics/
config/
– L
A
– generate pdf-documentation → refman_mod.pdf
1: cd docs/latex/
2: make -f Makeﬁle mod
18 / 29
Patrick Huck

View Slide

MySimpleExample/
README
configure.ac
Makefile.am
src/
bin/
docs/
Makefile mod
refman mod.tex
update texfile.sh
html/
latex/
refman mod.tex
Makefile mod
doxygen.sty
main.tex
classh simple.tex
man/
out/
pics/
config/
– L
A
– control distribution package with EXTRA_DIST and
dist_doc_DATA in Makefile.am
16: # distribution package extras
17: EXTRA DIST = src/mainpage.cc configure.ac Makefile.am
18: dist doc DATA = README
1: make dist # generate tarball
2: make clean # remove build files
3: make distclean # remove everything generated by automake
19 / 29
Patrick Huck

View Slide

Implement Class Structure Add Options Class
MySimpleExampleClass/
README
configure.ac
Makefile.am
src/
mainpage.cc
runhSimple.cc
hSimple/
hSimple.h
hSimple.cxx
LinkDef.h
bin/
runhSimple
docs/
out/
pics/
config/
– split hsimple() of src/hSimple.cc into hSimple.{h,cxx}
01: /* src/hSimple/hSimple.cxx */
11: ClassImp(hSimple)
13: hSimple::hSimple(TFile* pfile) { // init all private class members
24: void hSimple::Run(Int t niter) { // hSimple.C code
01: /* src/hSimple/hSimple.h */
10: #ifndef hSimple h
11: #define hSimple h
19: class hSimple {
20: private:
21: TH1F *hpx; TH2F *hpxpy; TProfile *hprof;
22: TNtuple *ntuple; TFile* hfile; TString png name;
23: public:
24: hSimple(TFile* pfile); // constructor
25: virtual ˜hSimple() {}; // destructor
26: void SetNamePNG(TString str) { png name = str.Data(); }
27: void Run(Int t niter = 25000) ;
28: ClassDef(hSimple,0)
29: };
30: #endif
– control class behaviour in src/runhSimple.cc
– put source code into src/hSimple/ and add LinkDef.h
– add dictionary generation and linking to Makefile.am
20 / 29
Patrick Huck

View Slide

README
configure.ac
Makefile.am
src/
mainpage.cc
runhSimple.cc
hSimple/
hSimple.h
hSimple.cxx
LinkDef.h
bin/
runhSimple
docs/
out/
pics/
config/
→ create hSimple object, SetNamePNG(), #Iterations
→ no hard coding in hSimple.{h,cxx}!
56: #include "hSimple/hSimple.h"
59: int main(int argc, char **argv) {
60: TRint* theApp = new TRint("App", &argc, argv, NULL, 0);
61: if ( theApp->Argc() == 2 ) {
64: hSimple *hs = new hSimple(hﬁle);
65: TString png name = "../pics/hSimple-Class.png";
66: hs->SetNamePNG(png name);
67: hs->Run(30000);
68: }
73: theApp->Run();
74: return 0;
75: }
21 / 29
Patrick Huck

View Slide

README
configure.ac
Makefile.am
src/
mainpage.cc
runhSimple.cc
hSimple/
hSimple.h
hSimple.cxx
LinkDef.h
bin/
runhSimple
docs/
out/
pics/
config/
1: /* src/hSimple/LinkDef.h */
2: #ifdef CINT
3: #pragma link off all globals;
4: #pragma link off all classes;
5: #pragma link off all functions;
6: #pragma link C++ nestedclasses;
7: #pragma link C++ nestedtypedefs;
8: #pragma link C++ class hSimple;
9: #endif
22 / 29
Patrick Huck

View Slide

README
configure.ac
Makefile.am
src/
mainpage.cc
runhSimple.cc
hSimple/
hSimple.h
hSimple.cxx
LinkDef.h
bin/
runhSimple
docs/
out/
pics/
config/
09: # hSimple dictionary/library
10: CLEANFILES = src/hSimple/hSimpleDict.cxx src/hSimple/hSimpleDict.h
11: pkglib LTLIBRARIES = src/hSimple/libhSimple.la
12: pkginclude HEADERS = src/hSimple/hSimple.h
13: noinst HEADERS = src/hSimple/LinkDef.h
14: src hSimple libhSimple la SOURCES = src/hSimple/hSimple.cxx
15: nodist src hSimple libhSimple la SOURCES = src/hSimple/hSimpleDict.cxx
16: # run rootcint
17: src/hSimple/hSimpleDict.cxx src/hSimple/hSimpleDict.h:src/hSimple/hSimple.h
src/hSimple/LinkDef.h
18: $(ROOTCINT) -f src/hSimple/hSimpleDict.cxx -c $(AM CPPFLAGS) $ˆ
19: # runhSimple
20: bin PROGRAMS = bin/runhSimple
21: bin runhSimple SOURCES = src/runhSimple.cc
22: bin runhSimple LDADD = src/hSimple/libhSimple.la
23: bin runhSimple LDADD += [email protected]@ @[email protected]
24: bin runhSimple LDADD += @[email protected] @[email protected] ${DEPS LIBS}
25: bin runhSimple LDFLAGS = -R $(ROOTLIBDIR) -L$(ROOTLIBDIR)
26: bin runhSimple CXXFLAGS = @[email protected]
23 / 29
Patrick Huck

View Slide

README
configure.ac
Makefile.am
src/
mainpage.cc
runhSimple.cc
hSimple/
hSimple.h
hSimple.cxx
LinkDef.h
bin/
runhSimple
docs/
out/
pics/
config/
How to avoid hard coding
entirely? Use program
options/parameters.
10: CLEANFILES = src/hSimple/hSimpleDict.cxx src/hSimple/hSimpleDict.h
11: pkglib LTLIBRARIES = src/hSimple/libhSimple.la
12: pkginclude HEADERS = src/hSimple/hSimple.h
13: noinst HEADERS = src/hSimple/LinkDef.h
14: src hSimple libhSimple la SOURCES = src/hSimple/hSimple.cxx
15: nodist src hSimple libhSimple la SOURCES = src/hSimple/hSimpleDict.cxx
16: # run rootcint
17: src/hSimple/hSimpleDict.cxx src/hSimple/hSimpleDict.h:src/hSimple/hSimple.h
src/hSimple/LinkDef.h
18: $(ROOTCINT) -f src/hSimple/hSimpleDict.cxx -c $(AM CPPFLAGS) $ˆ
19: # runhSimple
20: bin PROGRAMS = bin/runhSimple
21: bin runhSimple SOURCES = src/runhSimple.cc
22: bin runhSimple LDADD = src/hSimple/libhSimple.la
23: bin runhSimple LDADD += [email protected]@ @[email protected]
24: bin runhSimple LDADD += @[email protected] @[email protected] ${DEPS LIBS}
25: bin runhSimple LDFLAGS = -R $(ROOTLIBDIR) -L$(ROOTLIBDIR)
26: bin runhSimple CXXFLAGS = @[email protected]
2: ./conﬁgure
3: make
24 / 29
Patrick Huck

View Slide

README
configure.ac
Makefile.am
src/
mainpage.cc
runhSimple.cc
hSimple/
Options/
Options.h
Options.cxx
LinkDef.h
bin/
runhSimple
docs/
out/
pics/
config/
– easy to include foreign class Options.{h,cxx} to deal with optional
program parameters
i) save source ﬁles in separate folder under src/
ii) add corresponding LinkDef.h ﬁle
iii) include dictionary generation and linking in Makefile.am
[...]
09: # Options dictionary/library
10: CLEANFILES = src/Options/OptionsDict.cxx src/Options/OptionsDict.h
11: pkglib LTLIBRARIES = src/Options/libOptions.la
12: pkginclude HEADERS = src/Options/Options.h
13: noinst HEADERS = src/Options/LinkDef.h
14: src Options libOptions la SOURCES = src/Options/Options.cxx
15: nodist src Options libOptions la SOURCES = src/Options/OptionsDict.cxx
16: # run rootcint
17: src/Options/OptionsDict.cxx src/Options/OptionsDict.h:src/Options/Options.h src/Options/LinkDef.h
18: $(ROOTCINT) -f src/Options/OptionsDict.cxx -c $(AM CPPFLAGS) $ˆ
[...]
[...]
28: src hSimple libhSimple la LIBADD = src/Options/libOptions.la
[...]
35: bin runhSimple LDADD = src/Options/libOptions.la src/hSimple/libhSimple.la
[...]
– modify main-function in src/runhSimple.cc to deal with options
– fully control the program!
25 / 29
Patrick Huck

View Slide

README
configure.ac
Makefile.am
src/
mainpage.cc
runhSimple.cc
hSimple/
Options/
Options.h
Options.cxx
LinkDef.h
bin/
runhSimple
docs/
out/
pics/
config/
– easy to include foreign class Options.{h,cxx}
i) decode options & re-new argc/argv
ii) rewrite TRint application
61: // decode options
62: const char * optv[] = {"N:NIter ","O:NamePNG ",NULL} ;
63: Int t nit = 30000;
64: TString pngstr;
65: Options opts(*argv, optv);
66: OptArgvIter iter(--argc, ++argv);
67: const char *optarg;
68: int argcR = argc;
69: char **argvR;
70: while( char optchar = opts(iter, optarg) ) {
71: switch (optchar) {
72: case ’N’ :
73: nit = (Int t)atoi(optarg); argcR=argcR-2; break;
74: case ’O’ : pngstr = optarg; argcR=argcR-2; break;
75: default : break;
76: }
77: }
78: argvR = new char*[argcR];
79: Int t cnter = 0;
80: if (iter.index() < argc) {
81: for (int i = iter.index() ; i < argc ; i++) { argvR[cnter] = argv[i]; ++cnter; }
82: }
26 / 29
Patrick Huck

View Slide

README
configure.ac
Makefile.am
src/
mainpage.cc
runhSimple.cc
hSimple/
Options/
Options.h
Options.cxx
LinkDef.h
bin/
runhSimple
docs/
out/
pics/
config/
– easy to include foreign class Options.{h,cxx}
i) decode options & re-new argc/argv
ii) rewrite TRint application
84: TRint* theApp = new TRint("App", &argcR, argvR, NULL, 0);
85: if ( theApp->Argc() == 1 ) {
88: hSimple *hs = new hSimple(hﬁle);
89: if ( pngstr.Contains("png") ) hs->SetNamePNG(pngstr.Data());
90: hs->Run(nit);
91: }
96: theApp->Run();
1: runhSimple "out/hsimple.root"
2: runhSimple -N 1000000 "out/hsimple.root"
3: runhSimple -O "pics/test.png" "out/hsimple.root"
4: runhSimple -N 20000 -O "pics/test.png" "out/hsimple.root"
[...]
27 / 29
Patrick Huck

View Slide

MyAnalysis/
src/
BasePlot/
Bichsel/
Bichsel.h
Bichsel.cxx
dEdxParameterization.h
dEdxParameterization.cxx
MyPdgDatabase/
MyPdgDatabase.h
MyPdgDatabase.cxx
database
Embedding/
EmbeddingQA.h
MatchedPairsNT.h
McTracksNT.h
MyEventEmbData.h
SingleElectronNT.h
eeDecay.h
*.cxx
[...]
[...]
– from here on it’s easy to fill src/ and create your
Analysis Software.
– include foreign classes easily into this structure
→ BasePlot / Bichsel
– standard libraries with one header and one cxx file
work like the discussed hSimple example
– write your own utility classes providing functions or
databases frequently used (MyPdgDatabase)
→ works like the Options example
– compile multiple classes in one library and control
their interplay with the options of a single program
or with different programs
– very flexible including the advantages of known
Unix programs (options, one program for one task)
Conclusion:
With little effort one gets tidy, flexible, platform-
independent & easy-to-share Analysis Software including
man-pages, pdf-Documentation and Analysis Homepage
with the three easy commands
2: ./configure
3: make
28 / 29
Patrick Huck

View Slide

– http://www.openismus.com/documents/linux/automake/automake
– http://www.stack.nl/~dimitri/doxygen/index.html
– http://www.gnu.org/software/hello/manual/autoconf/
– http://www.gnu.org/software/hello/manual/automake/
– http://realmike.org/blog/2010/07/18/gnu-automake-by-example/
– http://chris-miceli.blogspot.com/2011/01/
integrating-doxygen-with-autotools.html
– http://ctan.org/tex-archive/macros/generic/dirtree/
– http://www.gnu.org/s/src-highlite/source-highlight.html
– http://www.cmcrossroads.com/bradapp/ftp/src/libs/C++/Options.html
– http://root.cern.ch/svn/root/tags/v5-24-00b/tutorials/hsimple.C
29 / 29
Patrick Huck

View Slide

Organize ROOT Analyses with Autoconf

Organize ROOT Analyses with Autoconf

Patrick Huck

Other Decks in Programming

Featured

Transcript