Current version is 0.11.
Distribution from this site.
CPAN site
NAME
SOOT - Use ROOT from Perl
SYNOPSIS
use SOOT ':all';
# more to follow
DESCRIPTION
SOOT is a Perl extension for using the ROOT library. It is very similar
to the Ruby-ROOT or PyROOT extensions for their respective languages.
Specifically, SOOT was implemented after the model of Ruby-ROOT.
Please note that SOOT is to be considered highly experimental at this
point. It uses a very dynamic approach to wrapping a very large and
quickly evolving library. Due to the dynamic nature (using the CInt
introspection), SOOT is able to handle most of the ROOT classes without
explicitly wrapping them. Some things are expected to not work because
not enough information about the API can be obtained automatically. Let
me know what you need and what is giving you problems and we'll work out
a solution.
In order to install and use SOOT, you need a configured ROOT library. In
particular, it is necessary that the root-config tool be executable and
findable via your "PATH" environment variable. Alternatively, you may
set the "ROOTSYS" environment variable. Please refer to the ROOT manual
for details.
Exports
By default, using SOOT does not export anything into your namespace. You
may choose to import the various ROOT-related global variables and/or
constants into your namespace either by explicitly listing them as
arguments to "use SOOT" or by importing the ":globals", ":constants", or
":all" tags:
use SOOT ':all';
# you now have $gApplication, $gSystem, kWhite etc
use SOOT qw($gApplication $gSystem);
# you now have only $gApplication and $gSystem
# you always have $SOOT::gApplication, etc!
use SOOT qw(kRed kDotted);
my $graph = TGraph->new(3);
$graph->SetLineColor(kRed);
$graph->SetLineStyle(kDotted);
The list of currently supported globals is:
$gApplication $gSystem $gRandom $gROOT
$gDirectory $gStyle $gPad $gBenchmark
$gEnv
$gHistImagePalette $gWebImagePalette
The list of currently exported functions:
Load(className, className2,...)
UpdateClasses()
JUMP-START FOR C++-ROOT USERS
This section outlines the differences between using ROOT from C++ or
from Perl via SOOT. If in doubt, the two should behave the same, but
there are a few subtle differences that a user must be aware of and
these should be documented here. If not, it's a bug.
Note about terminology: When referring to a ROOT object, the underlying
C++, TObject-derived object is meant. If the document mentions SOOT
objects, that is the Perl-level wrapper object.
Memory Management
ROOT has a fairly complex idea of object ownership which is documented
in its own section of the Users Manual
. SOOT tries to
implement a relatively simple and consistent memory management:
Any object that was created with a constructor is SOOT's responsibility
to clean up. All other objects are, by default, not freed by SOOT. That
means for objects created with "new()", the memory of the underlying
ROOT object will be freed when the last Perl-side reference to it goes
out of scope. SOOT implements its own reference counting "garbage
collection" in that you can create copies of SOOT objects that refer to
the same underlying ROOT object and there will be double-freed memory.
Examples:
sub test {
my $graph = TGraph->new(2, [0., 1.], [3., 5.]);
SCOPE: {
my $axis = $graph->GetXaxis();
my $otheraxis = $graph->GetXaxis();
# $axis and $otheraxis are really the same TObject underneath
}
# $axis and $otheraxis cease to exist, but don't free their TAxis
# objects because that would create a segmentation fault.
}
test();
# $graph won't exist here due to my's lexical scoping.
# $graph will free the memory of the underlying TGraph*!
# This also frees the TAxis and other sub-structures of the graph.
Sometimes, this behaviour is not what you want. You can usually work
around any problems by keeping references to objects around so that
they're not freed earlier than you would like. Alternatively, you can
manually mark objects as being owned by ROOT or SOOT:
# doesn't work because $cv goes out of scope
sub draw_histogram {
my $hist = shift;
my $cv = TCanvas->new("cv", "Awesome plot");
# style histogram and canvas here...
$hist->Draw();
}
my $histogram = ...
draw_histogram($histogram);
# $cv out of scope!
# Workaround 1: Pass around references.
sub draw_histogram2 {
my $hist = shift;
my $cv = TCanvas->new("cv", "Awesome plot");
$hist->Draw();
return $cv;
}
my $histogram = ...
my $canvas = draw_histogram($histogram);
# Workaround 2: Mark canvas object as global
sub draw_histogram3 {
my $hist = shift;
my $cv = TCanvas->new("cv", "Awesome plot")->keep;
$hist->Draw();
}
my $histogram = ...
draw_histogram($histogram);
# $cv is gone, but the TCanvas is held by ROOT.
# If necessary, you can get it again via $gROOT:
my $same_cv = $gROOT->FindObject('cv')->as('TCanvas');
# ...
# Later, you can manually delete an object:
$same_cv->delete; # deletes the UNDERLYING ROOT object, too!
The above examples introduce three methods for manual memory management
that are useful enough to highlight them again: "keep()" marks a SOOT
object as a global, that is, ROOT will hold on to the underlying TObject
even if all SOOT references to it have been garbage collected. "keep()"
will return the same SOOT object it was called on, for convenience.
In order to gain access to a ROOT object that is no longer accessible
via SOOT, you can use the usual "FindObject('name')" method of the
"TROOT" class via the $gROOT (or $SOOT::gROOT) global. This highlights
an important detail about the ROOT wrapper: "FindObject" returns a
generic "TObject*". In C++, you would cast it into a "TCanvas*":
TCanvas* same_cv = (TCanvas*)gROOT->FindObject('cv');
In the context of SOOT, explicit casting is done with the
"as('Typename')" method:
my $same_cv = $gROOT->FindObject('cv')->as('TCanvas');
"as('Typename')" returns a copy of the SOOT object it is called on with
a new type. Finally, the "delete()" method forcefully deletes a ROOT
object and all of its SOOT wrappers. It is possible to use this to crash
the program, so beware and use it sparingly.
Object Behaviour
Some operations are overloaded for all SOOT objects. Currently, you can
use the "==" comparison to check whether two SOOT objects refer to the
same ROOT object:
my $graph1 = TGraph->new(2, [1., 2.], [3., 4.]);
my $graph2 = TGraph->new(1, [4.], [8.2]);
my $g1_copy = $graph1; # actually a shallow copy...
say '$graph1 and $g1_copy are the same'
if $graph1 == $g1_copy;
say '$graph1 and $graph2 are the same'
if $graph1 == $graph2;
This will print:
$graph1 and $g1_copy are the same
Availability of ROOT Classes
By default, SOOT loads most of the available ROOT classes and wraps them
for use in Perl. If some class is not available, you may try to load it
as follows:
SOOT::Load( qw(TSomeClass TAnotherClassILike) );
"Load" will automatically try to load the specified classes' base
classes as well. In future, it might be extended to inspect the class
members and load any other ROOT classes that are part of its interface.
If you want to use classes from a shared library that is not loaded by
default, everything should work if you do the following:
$gSystem->Load('libGeom.so');
$gSystem->Load('libGeomBuilder.so');
SOOT::UpdateClasses(); # Bind ALL new classes
Alternatively you may bind only what you need:
$gSystem->Load('libGeom.so');
$gSystem->Load('libGeomBuilder.so');
SOOT::Load('TGeoMaterial'); # or whatever
Updating all classes may be a relatively slow operation. A third
approach is using the special TSystem::LoadNUpddate method which is not
part of the normal ROOT interface:
$gSystem->Load('libGeom.so');
$gSystem->LoadNUpdate('libGeomBuilder.so');
"LoadNUpdate()" will bind any new classes if the library was loaded
successfully and wasn't loaded before.
FUNCTIONS
Load
Loads one or more ROOT classes and their base classes into Perl.
Virtually all ROOT classes should be loaded out of the box. This
function is only necessary if you load additional shared libraries.
UpdateClasses
After loading non-standard shared libraries that provide ROOT-based
classes, it may be necessary to update the Perl-bindings for those
classes. You may either use "Load()" if you know which exact classes you
want to bind, or you may call "SOOT::UpdateClasses()" to check the whole
ROOT class table for classes that were previously not available to Perl.
INSTALLATION
Eventually, SOOT *might* be shipped with ROOT. Until that happens, you
need to do the following: Set your ROOT paths as usual. Make sure the
root-config program is available and executable via the "PATH".
Then build SOOT like any other CPAN module. To install a release from
CPAN, type:
sudo cpan SOOT
To do so manually, do:
tar -xzf SOOT-0.XX.tar.gz
cd SOOT-0.XX
perl Makefile.PL
make
make test
(sudo make install)
Without installing, you may run the SOOT examples from the SOOT
directory where you just typed "make" as follows:
perl -Mblib examples/Hist/hstack.pl
The "-Mblib" indicates that perl should preferably load modules from the
blib (read: "build-library") directory of the current directory which
contains the uninstalled SOOT library.
NOTE: At this point, SOOT requires a copy of ROOT that has been
configured with the "--enable-explicitlink" option, which -- sadly --
isn't the default.
SEE ALSO
SOOT::API exposes some of the underlying SOOT-internals.
SOOT::Struct allows for run-time creation/compilation of ROOT/C-level
structs. Structs created this way are available from Perl.
SOOT::App implements a root.exe/CInt-like front-end using Devel::REPL.
It is not part of SOOT and is available separately from CPAN.
ACKNOWLEDGMENTS
Eric Wilhelm and David Golden put up with my stupid questions about
Module::Build and always stayed civil and helpful. Thanks for that!
AUTHOR
Steffen Mueller,
COPYRIGHT AND LICENSE
Copyright (C) 2010 by Steffen Mueller
SOOT, the Perl-ROOT wrapper, is free software; you can redistribute it
and/or modify it under the same terms as ROOT itself, that is, the GNU
Lesser General Public License. A copy of the full license text is
available from the distribution as the LICENSE file.
SOOT
SOOT::API
SOOT::Struct
SOOT::Examples::Images
SOOT::Examples::Hist
SOOT::Examples::Math
SOOT::Examples::Basic
SOOT::Examples::Graph
SOOT::Examples::Geometry
Revision history for Perl extension SOOT.
0.11 Tue Sep 21 21:00 2010
* Bug fixes:
- Compile fix in PtrTable for some gccs.
0.10 Tue Sep 21 20:00 2010
* Bug fixes:
- Better error reporting (no more false error location
in TObject.pm)
* New features:
- Optimized TF1::GetRandom calls
- Wrapped TFitResultPtr
- Updated examples.
- Updated all the bundled modules.
0.09 Wed Apr 21 18:00 2010
* New features:
- Using Alien::ROOT, on which we now depend at configure time,
it's possible to get an entirely working, private copy of ROOT
for SOOT. That means on a virgin (Linux!) machine, you can do the
following to install SOOT and all of its dependencies:
$ cpan SOOT
- Now using Alien::ROOT to detect ROOT.
0.08 Sun Apr 11 12:12 2010
* Bug Fixes:
- Perl 5.12 compatibility.
- Now buildable on unthreaded perls.
* New features:
- SOOT::Struct: Dynamic struct generation
You can use SOOT::Struct to create new C-level struct types
at run-time. These structs are then also available as Perl
classes with the corresponding accessor methods for the
struct attributes.
- RunTimeXS: Cached accessor methods for structs.
RunTimeXS is a mechanism to create XSUBs at run time. It's
currently used to install the accessor methods for structs.
This brings a 60-fold speed-up for struct access:
O(millions) calls per second!
* Internals:
- unsigned int array conversions
- AVToIntegerVecInPlace and friends for conversion of an
AV to existing, pre-allocated data members
* Updates, etc:
- Brought bundled Module::Build and ExtUtils::CBuilder up to date.
0.07 Wed Mar 30 20:00 2010
* Bug Fixes:
- Fix memory leak on each method call.
=> currently all leak checks pass!
- Call *correct* object destructors before free-ing ROOT objects.
* Internals:
- Some refactoring
=> Replace macro IS_TOBJECT with an inlined function.
=> Better debugging mode/output
=> Better leak tests
=> Replace some use of char* with std::strings
0.06 Fri Mar 26 20:00 2010
* New features:
- Conversion to Module::Build!
- All non-core build-time dependencies should be bundled now.
- Expose $gHistImagePalette $gWebImagePalette
- Quite a few more examples.
- Copy constructors.
- Installation documentation
- SOOT->LoadNUpdate('libGeomBuilder.so');
=> Will load the shared library and regenerate the class templates.
* Bug fixes:
- Fix for method calling bug wrt. invalidated MethodInfo.
* Internals:
- AUTOLOAD bootstrapping now done in XS (read: C) for performance.
- Various simplifications and refactoring of the internals.
0.05 Mon Mar 8 20:00 2010
- Completely revamped the way that the ROOT classes are bootstrapped.
- Fix for the "enum*" return value bug (cf. TH1D::GetXaxis())
- Implemented function calling (I.e. TMath::Abs())
=> Hacky implementation, needs revisiting.
- TF1::GetParErrors() returns a Perl array now and so does
TFormula::GetParameters()
- Optimizations in TObjectEncapsulation.
- Fix for the return value of SOOT::API::type()
- SOOT::API::is_same_tobject() (and tests for object equality)
- SOOT::API::is_soot_class()
- Started documenting SOOT <-> ROOT differences for users
- Many more examples
0.04 Fri Feb 26 21:00 2010
- Memory leak fixes.
- Inlined copy of toolchain => Doesn't fully work for building
the src/ subdirectory yet.
- Examples now also shipped as documentation.
- Manual casting with $axis->as('TAxis')
This is sometimes necessary to work around mistakes in
the type inference.
- $obj->keep() to manually mark an object as "do not free this
on behalf of Perl".
- Expose $gEnv.
- Expose SOOT::Init(bool) which intializes the underlying TCint
and (if bool is true) load the .rootrc logon macros (C!).
- Inheritance-respecting, recursive class generation.
- SOOT::Load(className, ...) for exposing extra ROOT classes to
Perl.
- Pointer-table state can be dumped for debugging (see GC
item below).
- Added complete reference counting "garbage collector"
or rather ROOT<->Perl memory interface a la PyROOT's
TMemoryRegulator.
0.03 Sun Feb 21 21:00 2010
- Many more examples.
- Lazy initialization of ROOT globals (gPad!)
- Constants actually work now.
- gBenchmark
- TH1* doesn't inherit from TArray in the wrapper - for now.
- TArray* construction from Perl arrays:
my $tarrayd = TArrayD->new([1., 2., ...]);
- More tests!
0.02 Sat Feb 20 17:30 2010
- List of candidate methods shown on bad method invocation.
- Fixed problems with globals (gROOT, etc) and global
interpreter destruction.
- Implemented wrapping of more globals: gStyle, gDirectory,
gROOT, gSystem, etc.
- A bunch of examples (some working, some not yet) in examples/
- Recognize "short" as integer type.
- Fixed memory leak of array-of-basic-type arguments and return
types.
- Fixed MethodInfo leak.
- Reference/Pointer equality. "const" references still to-do.
- More Perl-SOOT API: Class name iterator.
- Allow export of various constants/enums such as kRed, kTRUE, etc.
0.01 Tue Feb 9 19:31 2010
- original version
(c) 2002-2010 Steffen Müller; All rights reserved.