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