doc/man/skeletons.1

0001 .TH "SKELETONS" "1" "February 25, 2013" "development" "Skeletons"
0002 .SH NAME
0003 skeletons \- Skeletons Documentation
0004 .
0005 .nr rst2man-indent-level 0
0006 .
0007 .de1 rstReportMargin
0008 \\$1 \\n[an-margin]
0009 level \\n[rst2man-indent-level]
0010 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
0011 -
0012 \\n[rst2man-indent0]
0013 \\n[rst2man-indent1]
0014 \\n[rst2man-indent2]
0015 ..
0016 .de1 INDENT
0017 .\" .rstReportMargin pre:
0018 . RS \\$1
0019 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
0020 . nr rst2man-indent-level +1
0021 .\" .rstReportMargin post:
0022 ..
0023 .de UNINDENT
0024 . RE
0025 .\" indent \\n[an-margin]
0026 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
0027 .nr rst2man-indent-level -1
0028 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
0029 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
0030 ..
0031 .\" Man page generated from reStructuredText.
0032 .
0033 .SH INTRODUCTION
0034 .sp
0035 Skeletons is a general purpose template system. It is designed to support any
0036 type of templates, e.g. C++, python, etc., via template package where you keep
0037 your templates. It supports template and example tags within your template, as
0038 well as coding within your template via python language.
0039 .SH CMS COMMANDS
0040 .sp
0041 The following CMS commands is available for your needs:
0042 .INDENT 0.0
0043 .IP \(bu 2
0044 \fBmkdatapkg\fP generates code based on DataPkg template
0045 .IP \(bu 2
0046 \fBmkedanlzr\fP generates code based on EDAnalyzer template
0047 .IP \(bu 2
0048 \fBmkedfltr\fP generates code based on EDFilter template
0049 .IP \(bu 2
0050 \fBmkedlpr\fP generates code based on EDLooper template
0051 .IP \(bu 2
0052 \fBmkedprod\fP generates code based on EProducer template
0053 .IP \(bu 2
0054 \fBmkesprod\fP generates code based on ESProcuder template
0055 .IP \(bu 2
0056 \fBmkevhyp\fP generates code based on EventHypothesis template
0057 .IP \(bu 2
0058 \fBmkrecord\fP generates code based on Record template
0059 .IP \(bu 2
0060 \fBmkskel\fP generates code based on Skeleton template
0061 .UNINDENT
0062 .sp
0063 The \fBmkrecord\fP and \fBmkskel\fP scripts will run anywhere on your system, while
0064 others requires that you should be within $CMSSW_BASE/src area. All scripts
0065 provides suitable help message and will guide you through the code generation
0066 process.
0067 .SH MKTMPL COMMAND
0068 .sp
0069 There is a general purpose \fBmktmpl\fP command which can be used to generate
0070 your favorite template. It has the following options:
0071 .INDENT 0.0
0072 .INDENT 3.5
0073 .sp
0074 .nf
0075 .ft C
0076 Usage: mktmpl [options]
0077
0078 Options:
0079   \-h, \-\-help           show this help message and exit
0080   \-\-debug              debug output
0081   \-\-tmpl=TMPL          specify template, e.g. EDProducer
0082   \-\-name=PNAME         specify package name, e.g. MyProducer
0083   \-\-author=AUTHOR      specify author name
0084   \-\-ftype=FTYPE        specify file type to generate, e.g. \-\-generate=header,
0085                        default is all files
0086   \-\-keep\-etags=KETAGS  list examples tags which should be kept in generate
0087                        code, e.g. \-\-keep\-etags=\(aq@example_trac,@example_hist\(aq
0088   \-\-tdir=TDIR          specify template directory,
0089   \-\-tags               list template tags
0090   \-\-etags              list template example tags
0091   \-\-templates          list supported templates
0092 .ft P
0093 .fi
0094 .UNINDENT
0095 .UNINDENT
0096 .sp
0097 For example if you\(aqd like to generate CMS EDProducer package you can use mktmpl
0098 with the following set of options
0099 .INDENT 0.0
0100 .INDENT 3.5
0101 .sp
0102 .nf
0103 .ft C
0104 mktmpl \-\-tmpl=EDProducer \-\-name=MyProducer
0105 .ft P
0106 .fi
0107 .UNINDENT
0108 .UNINDENT
0109 .sp
0110 You can list available templates via the following command:
0111 .INDENT 0.0
0112 .INDENT 3.5
0113 .sp
0114 .nf
0115 .ft C
0116 mktmpl \-\-templates
0117 .ft P
0118 .fi
0119 .UNINDENT
0120 .UNINDENT
0121 .sp
0122 Finally, to list available template and example tags you can use the following
0123 commands:
0124 .INDENT 0.0
0125 .INDENT 3.5
0126 .sp
0127 .nf
0128 .ft C
0129 mktmpl \-\-tmpl=EDProducer \-\-tags
0130 mktmpl \-\-tmpl=EDProducer \-\-etags
0131 .ft P
0132 .fi
0133 .UNINDENT
0134 .UNINDENT
0135 .SH PACKAGE TEMPLATES
0136 .sp
0137 Skeletons template system uses user\-defined templates which may have arbitrary
0138 file structure within template directory. The name of template directory defines a
0139 template type available to the end\-users.
0140 .sp
0141 In order to extend Skeletons package with your own template package you need
0142 to create it within scripts/mkTemplates area of Skeletons package. The new
0143 template package may contain arbitrary set of files and any directory
0144 structure. But you need to provide a \fIDriver.dir\fP file with such structure.
0145 For instance, if you want to create template package \fIFoo\fP with
0146 src/test/include directories, Foo.cc file in src area, Foo.h in include area
0147 and top\-level makefile your \fIDriver.dir\fP file will have the following structure:
0148 .INDENT 0.0
0149 .INDENT 3.5
0150 .sp
0151 .nf
0152 .ft C
0153 Makefile
0154 src/Foo.cc
0155 test/
0156 include/Foo.h
0157 .ft P
0158 .fi
0159 .UNINDENT
0160 .UNINDENT
0161 .sp
0162 In order to write your template files, e.g. Foo.cc, Foo.h and Makefile, please
0163 consult Skeletons rules section.
0164 .SS Skeletons rules
0165 .sp
0166 There are two types of tags supported by Skeletons package, template and example
0167 tags. Template tags can use any name which should be enclosed with double
0168 underscores, e.g. \fI__test__\fP, \fI__prodname__\fP, \fI__abc123__\fP. The example tags
0169 should start with \fI@example_\fP prefix followed by the name, e.g. \fI@example_track\fP.
0170 .sp
0171 In addition to template and example tags, user can write python snippets in their
0172 template, which should be enclosed with two statements: \fI#python_begin\fP and
0173 \fI#python_end\fP. PLEASE NOTE: you must use proper identination for python snippets
0174 similar to normal python code requirements.
0175 .sp
0176 For example:
0177 .INDENT 0.0
0178 .INDENT 3.5
0179 .sp
0180 .nf
0181 .ft C
0182 #python_begin
0183     output = []
0184     for dtype in __datatypes__:
0185         ptr = "std::shared_ptr<%s> p%s;" % dtype
0186         output.append(ptr)
0187     print output
0188 #python_end
0189 .ft P
0190 .fi
0191 .UNINDENT
0192 .UNINDENT
0193 .sp
0194 Here we created an output vector which stores strings of shared pointers for
0195 data types found in __datatypes__ template tag. Finally we printed out output
0196 vector content. Any print statement will be captured and its context will be
0197 added to your templates.  In this case if you supply __datatypes__ with array
0198 of data types you want to create in python snippet, e.g. __datatypes__=[\(aqint\(aq,
0199 \(aqdouble\(aq], the Skeletons engine will replace this python snippet with the
0200 following:
0201 .INDENT 0.0
0202 .INDENT 3.5
0203 .sp
0204 .nf
0205 .ft C
0206 std::shared_ptr<int> pint;
0207 std::shared_ptr<double> pdouble;
0208 .ft P
0209 .fi
0210 .UNINDENT
0211 .UNINDENT
0212 .sp
0213 Event though we do not impose any restriction on tag naming convention it is
0214 wise to use them appropriately, e.g. for your C++ class template you are better
0215 use \fI__class__\fP and similar tag name conventions.
0216 .SS Driver.dir file
0217 .sp
0218 In some cases you\(aqd like to generate your template according to some directory
0219 structure. To make this happens you need to place into your template package
0220 the \fIDriver.dir\fP file whose context should outline a final directory structure
0221 of generated package. For instance, let\(aqs say that your template package has
0222 source and header c++ files as well as Makefile:
0223 .INDENT 0.0
0224 .INDENT 3.5
0225 .sp
0226 .nf
0227 .ft C
0228 MyPackage.cc, MyPackage.h, Makefile
0229 .ft P
0230 .fi
0231 .UNINDENT
0232 .UNINDENT
0233 .sp
0234 and you\(aqd like to create the following directory layout:
0235 .INDENT 0.0
0236 .INDENT 3.5
0237 .sp
0238 .nf
0239 .ft C
0240 MyPackage
0241 |\-\- Makefile
0242 |   include/
0243 |   |\-\- MyPackage.h
0244 |   src/
0245 |   |\-\- MyPackage.cc
0246 .ft P
0247 .fi
0248 .UNINDENT
0249 .UNINDENT
0250 .sp
0251 To instruct Skeletons engine to generate such directory structure and put files
0252 in place you create \fIDriver.dir\fP inside of your package template with the
0253 following context:
0254 .INDENT 0.0
0255 .INDENT 3.5
0256 .sp
0257 .nf
0258 .ft C
0259 Makefile
0260 incldue/MyPackage.h
0261 src/MyPackage.cc
0262 .ft P
0263 .fi
0264 .UNINDENT
0265 .UNINDENT
0266 .sp
0267 The Skeletons engine will use theis file, create include,
0268 src directories and place generated files in appropriate locations.
0269 .SH EXAMPLE
0270 .sp
0271 Let\(aqs create a new template package and call it MyPackage. This package will
0272 have a header file in include directory and source file in src directory.
0273 We also want to have top\-level Makefile. With this set of requirements we
0274 need to create the following template directory
0275 .INDENT 0.0
0276 .INDENT 3.5
0277 .sp
0278 .nf
0279 .ft C
0280 mkdir <path>/scripts/mkTemplates/MyPackage
0281 .ft P
0282 .fi
0283 .UNINDENT
0284 .UNINDENT
0285 .sp
0286 Here the \fI<path>\fP refers to location of Skeleton scripts area. Now we need to
0287 create Driver.dir file which will instruct Skeleton engine about our intention.
0288 .INDENT 0.0
0289 .INDENT 3.5
0290 .sp
0291 .nf
0292 .ft C
0293 cd <path>/scripts/mkTemplates/MyPackage
0294 cat > Driver.dir << EOF
0295 Makefile
0296 src/MyPackage.cc
0297 include/MyPackage.h
0298 test
0299 EOF
0300 .ft P
0301 .fi
0302 .UNINDENT
0303 .UNINDENT
0304 .sp
0305 Here we created a Driver.dir file with appropriate content. Now let\(aqs move on
0306 and create our template files. Our first file is MyPackage.h:
0307 .INDENT 0.0
0308 .INDENT 3.5
0309 .sp
0310 .nf
0311 .ft C
0312 #ifndef __class___ESPRODUCER_h
0313 #define __class___ESPRODUCER_h
0314 //
0315 // class declaration
0316 //
0317 class __class__ : public edm::ESProducer {
0318    public:
0319       __class__(const edm::ParameterSet&);
0320       ~__class__();
0321
0322 #python_begin
0323     datatypes = []
0324     for dtype in __datatypes__:
0325         datatypes.append("std::shared_ptr<%s>" % dtype)
0326     print "      typedef edm::ESProducts<%s> ReturnType;" % \(aq,\(aq.join(datatypes)
0327 #python_end
0328
0329       ReturnType produce(const __record__&);
0330    private:
0331       // \-\-\-\-\-\-\-\-\-\-member data \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
0332 };
0333 #endif // end of __class___ESPRODUCER_h define
0334 .ft P
0335 .fi
0336 .UNINDENT
0337 .UNINDENT
0338 .sp
0339 As you may noticed we used Skeleton placeholders tags with double underscores.
0340 (You can use any name surrounded by double underscores and will need to feed
0341 their content via mk\-script). Here we use \fI__class__\fP to refer the class name
0342 and so on.
0343 .sp
0344 Here is content for our MyPackage.cc file:
0345 .INDENT 0.0
0346 .INDENT 3.5
0347 .sp
0348 .nf
0349 .ft C
0350 // \-*\- C++ \-*\-
0351 //
0352 // Package        :  __name__
0353 // Class          :  __class__
0354 // Original Author:  __author__
0355 //         Created:  __date__
0356
0357 //
0358 // constructors and destructor
0359 //
0360 __class__::__class__(const edm::ParameterSet& iConfig)
0361 {
0362    setWhatProduced(this);
0363 }
0364
0365 __class__::~__class__()
0366 {
0367    // do anything here that needs to be done at desctruction time
0368 }
0369
0370
0371 //
0372 // member functions
0373 //
0374
0375 // \-\-\-\-\-\-\-\-\-\-\-\- method called to produce the data  \-\-\-\-\-\-\-\-\-\-\-\-
0376 __class__::ReturnType
0377 __class__::produce(const __record__& iRecord)
0378 {
0379    using namespace edm::es;
0380 #python_begin
0381     out1 = []
0382     out2 = []
0383     for dtype in __datatypes__:
0384         out1.append("   std::shared_ptr<%s> p%s;\en" % (dtype, dtype))
0385         out2.append("p%s" % dtype)
0386     output  = \(aq\en\(aq.join(out1)
0387     output += "   return products(%s);\en" % \(aq,\(aq.join(out2)
0388     print output
0389 #python_end
0390 }
0391
0392 //define this as a plug\-in
0393 DEFINE_FWK_EVENTSETUP_MODULE(__class__);
0394 .ft P
0395 .fi
0396 .UNINDENT
0397 .UNINDENT
0398 .sp
0399 The content of Makefile is not relevant here and can be anything you like.
0400 .sp
0401 Finally, we create mkmypkg shell script in Skeletons/bin area with the
0402 following context:
0403 .INDENT 0.0
0404 .INDENT 3.5
0405 .sp
0406 .nf
0407 .ft C
0408 #!/bin/sh
0409 # find out where Skeleton is installed on a system
0410 sroot=\(gapython \-c "import Skeletons; print \(aq/\(aq.join(Skeletons.__file__.split(\(aq/\(aq)[:\-1])"\(ga
0411 # run actual script
0412 export SKL_PRGM=mkmypkg
0413 python $sroot/main.py \-\-type=MyPackage ${1+"$@"}
0414 .ft P
0415 .fi
0416 .UNINDENT
0417 .UNINDENT
0418 .sp
0419 With all of this in place we are ready to use our template as following:
0420 .INDENT 0.0
0421 .INDENT 3.5
0422 .sp
0423 .nf
0424 .ft C
0425 mkmypkg \-\-name=TestPackage "__record__=MyRecord" "__datatypes__=[\(aqint\(aq,
0426 \(aqdouble\(aq]"
0427 .ft P
0428 .fi
0429 .UNINDENT
0430 .UNINDENT
0431 .sp
0432 It will generate the following structure of new package:
0433 .INDENT 0.0
0434 .INDENT 3.5
0435 .sp
0436 .nf
0437 .ft C
0438 TestPackage/
0439 |  include/
0440 |  |\-\- TestPackage.h
0441 |  src/
0442 |  |\-\- TestPackage.cc
0443 |  test/
0444 |  Makefile
0445 .ft P
0446 .fi
0447 .UNINDENT
0448 .UNINDENT
0449 .sp
0450 For more ideas please inspect any of the existing templates, e.g. c++11, which
0451 can be found in Skeleton scripts/mkTemplates/ area.
0452 .SH SKELETON CORE CLASSES
0453 .sp
0454 File       : Skeleton.py
0455 Author     : Valentin Kuznetsov <\fI\%vkuznet@gmail.com\fP>
0456 Description:
0457 .INDENT 0.0
0458 .TP
0459 .B class Skeletons.main.SkeletonOptionParser
0460 Skeleton option parser
0461 .INDENT 7.0
0462 .TP
0463 .B get_opt()
0464 Returns parse list of options
0465 .UNINDENT
0466 .UNINDENT
0467 .INDENT 0.0
0468 .TP
0469 .B Skeletons.main.generator()
0470 Code generator function, parse user arguments and load appropriate
0471 template module. Once loaded, run its data method depending on
0472 user requested input parameter, e.g. print_etags, print_tags or
0473 generate template code.
0474 .UNINDENT
0475 .INDENT 0.0
0476 .TP
0477 .B Skeletons.main.parse_args(args)
0478 Parse input arguments
0479 .UNINDENT
0480 .INDENT 0.0
0481 .TP
0482 .B Skeletons.main.tmpl_dir()
0483 Retturn default location of template directory
0484 .UNINDENT
0485 .sp
0486 File       : pkg.py
0487 Author     : Valentin Kuznetsov <\fI\%vkuznet@gmail.com\fP>
0488 Description: AbstractGenerator class provides basic functionality
0489 to generate CMSSW class from given template
0490 .INDENT 0.0
0491 .TP
0492 .B class Skeletons.pkg.AbstractPkg(config=None)
0493 AbstractPkg takes care how to generate code from template/PKG
0494 package area. The PKG can be any directory which may include
0495 any types of files, e.g. C++ (.cc), python (.py), etc.
0496 This class relies on specific logic which we outline here:
0497 .INDENT 7.0
0498 .INDENT 3.5
0499 .INDENT 0.0
0500 .IP \(bu 2
0501 each template may use tags defined with double underscores
0502 enclosure, e.g. __class__, __record__, etc.
0503 .IP \(bu 2
0504 each template may have example tags, such tags should
0505 start with @example_. While processing template user may
0506 choose to strip them off or keep the code behind those tags
0507 .IP \(bu 2
0508 in addition user may specify pure python code which can
0509 operate with user defined tags. This code snipped should
0510 be enclosed with #python_begin and #python_end lines
0511 which declares start and end of python block
0512 .UNINDENT
0513 .UNINDENT
0514 .UNINDENT
0515 .INDENT 7.0
0516 .TP
0517 .B generate()
0518 Generate package templates in a given directory
0519 .UNINDENT
0520 .INDENT 7.0
0521 .TP
0522 .B get_kwds()
0523 Return keyword arguments to be used in methods
0524 .UNINDENT
0525 .INDENT 7.0
0526 .TP
0527 .B parse_etags(line)
0528 Determine either skip or keep given line based on class tags
0529 meta\-strings
0530 .UNINDENT
0531 .INDENT 7.0
0532 .TP
0533 .B print_etags()
0534 Print out template example tags
0535 .UNINDENT
0536 .INDENT 7.0
0537 .TP
0538 .B print_tags()
0539 Print out template keys
0540 .UNINDENT
0541 .INDENT 7.0
0542 .TP
0543 .B tmpl_etags()
0544 Scan template files and return example tags
0545 .UNINDENT
0546 .INDENT 7.0
0547 .TP
0548 .B tmpl_tags()
0549 Scan template files and return template tags
0550 .UNINDENT
0551 .INDENT 7.0
0552 .TP
0553 .B write(fname, tmpl_name, kwds)
0554 Create new file from given template name and set of arguments
0555 .UNINDENT
0556 .UNINDENT
0557 .sp
0558 File       : utils.py
0559 Author     : Valentin Kuznetsov <\fI\%vkuznet@gmail.com\fP>
0560 Description: Utilities module
0561 .INDENT 0.0
0562 .TP
0563 .B Skeletons.utils.code_generator(kwds)
0564 Code generator function, parse user arguments, load and
0565 return appropriate template generator module.
0566 .UNINDENT
0567 .INDENT 0.0
0568 .TP
0569 .B Skeletons.utils.functor(code, kwds, debug=0)
0570 Auto\-generate and execute function with given code and configuration
0571 For details of compile/exec/eval see
0572 \fI\%http://lucumr.pocoo.org/2011/2/1/exec-in-python/\fP
0573 .UNINDENT
0574 .INDENT 0.0
0575 .TP
0576 .B Skeletons.utils.parse_word(word)
0577 Parse word which contas double underscore tag
0578 .UNINDENT
0579 .INDENT 0.0
0580 .TP
0581 .B Skeletons.utils.test_env(tdir, tmpl)
0582 Test user environment, look\-up if user has run cmsenv, otherwise
0583 provide meaningful error message back to the user.
0584 .UNINDENT
0585 .INDENT 0.0
0586 .TP
0587 .B Skeletons.utils.tree(idir)
0588 Print directory content, similar to tree UNIX command
0589 .UNINDENT
0590 .INDENT 0.0
0591 .TP
0592 .B Skeletons.utils.user_info(ainput=None)
0593 Return user name and office location, based on UNIX finger
0594 .UNINDENT
0595 .sp
0596 File       : cms.py
0597 Author     : Valentin Kuznetsov <\fI\%vkuznet@gmail.com\fP>
0598 Description: CMS\-related utils
0599 .INDENT 0.0
0600 .TP
0601 .B Skeletons.cms.cms_error()
0602 Standard CMS error message
0603 .UNINDENT
0604 .INDENT 0.0
0605 .TP
0606 .B Skeletons.cms.config(tmpl, pkg_help, tmpl_dir)
0607 Parse input arguments to mk\-script
0608 .UNINDENT
0609 .INDENT 0.0
0610 .TP
0611 .B Skeletons.cms.generate(kwds)
0612 Run generator code based on provided set of arguments
0613 .UNINDENT
0614 .INDENT 0.0
0615 .TP
0616 .B Skeletons.cms.test_cms_environment(tmpl)
0617 Test CMS environment and requirements to run within CMSSW_BASE.
0618 Return True if we fullfill requirements and False otherwise.
0619 .UNINDENT
0620 .INDENT 0.0
0621 .IP \(bu 2
0622 \fIgenindex\fP
0623 .IP \(bu 2
0624 \fImodindex\fP
0625 .IP \(bu 2
0626 \fIsearch\fP
0627 .UNINDENT
0628 .SH AUTHOR
0629 Valentin Kuznetsov
0630 .SH COPYRIGHT
0631 2013, Valentin Kuznetsov
0632 .\" Generated by docutils manpage writer.
0633 .