IOStreams Migration
This page compiles information on migrating BaBar code from the
so-called classic iostreams to standard iostreams.
Send questions/comments to Rainer Bartoldus.
Quick links:
[What's this?]
[Migration Tools]
[Migrated Releases]
[Validation Tests]
[Building against a migrated release]
What's this?
When BaBar started coding in C++, no standard existed yet for the C++
input/output libraries. As a consequence, up to today our complete
code base remains based on the use of the original, pre-standard or
"classic" iostreams.
Recall, the iostreams library is
what allows you to compile a line of code like:
cout << "Hello world!" << endl;
Meanwhile, all modern compilers, including the two we currently use in
BaBar, adhere to the official standard. Moreover, newer compilers
have dropped support for the classic iostreams. To make
those newer compilers available to us, we need to migrate our code.
The most visible difference between the standard and the classic
implementation may be that, instead of:
#include <iostream.h> // classic header
the standard headers are included without the .h suffix,
namely:
#include <iostream> // standard header
This makes them look just like the other STL headers
<vector>, <string> etc.
In addition, the standard iostreams objects are all
defined inside the std:: namespace. So you need to write:
std::cout << "Hello world" << std::endl;
or, put either
using std::cout;
using std::endl;
or
using namespace std;
ahead of the above statement. (More on our policies for using
declarations below. Just remember that we generally don't allow
using declarations in header files, but encourage them in
source files.)
These two may be the most frequent changes you need to make when
migrating code from the classic to the standard iostreams,
but they are by far not all of them. There will be more on other
differences in a separate section.
Migration Tools
Over the past year or so we have developed a suite of scripts that can
perform a virtually automatic migration of our current releases. This
took a lot of tuning on existing code, and in the process we have
tagged O(100) packages in backward-compatible ways as preparation for
the automated tools. As a result, most of our released code now
migrates fine.
There is a list of about 10 packages that make use of features which
were not included or were changed in the standard, and these packages
needed to be migrated by hand. The packages currently include, with
respect to release 14.5.2:
BdbAdminTools V01-00-06
BdbClusteringServer V01-01-02
BdbCondTests V00-05-02
BdbEvent V03-00-26
BdbUtil V02-01-00
BunchT0 V01-00-10
CLHEP V01-06-07
EidData V00-04-00
EmcOep V00-02-08
EmcSrcCalApps V00-02-18
OdfCommon V00-07-00
OepBuffer V00-02-00
All the remaining (about 850) released packages will be taken care of
by the suite of scripts.
In general, developers should not need to bother knowing what those
individual scripts are. However, in brief terms, they include:
| IOSMigrateAll
| This is the top-level wrapper that performs a complete migration
by calling all other scripts recursively on a package or a test
release directory.
| | IOSFixIncludeStreamH
| This script fixes up some includes of the obsolete
<stream.h> header.
| | IOSAddIncludeBaBarHH
| This script adds the BaBar.hh header to all .cc and
.cpp files that should contain it, but don't.
| | IOSAddIncludeBaBarHH
| This script is the central part of the suite and performs the
actual migration. It distinguishes header and source files and runs
through all necessary steps of changing #include directives,
replacing forward declarations, adding std:: scope
resolutions and adding explicit using declarations.
| | IOSRepairFlush
| This script cures a particular side-effect that the main
migration script has on the .hh files of a few individual
packages.
| | IOSFixSeekoff
| This script addresses a particular migration task that only
applies to a couple of our packages.
|
The above scripts are all built as the extrabinscripts target
of the IOStreamUtils package:
$ gmake IOStreamUtils.extrabinscripts
If you are using a migrated base release, you shouldn't need to do
this yourself.
Migrated Releases
We have been migrating releases for quite some time. Doing this made
it possible to develop the migration tools and address a number of
issues that arose with the migrated code. Recent migration builds
have been shown to be basically functional. We are now making these
migrated builds available to all developers and users.
Migrated builds use exactly the same package tags as the releases they
are derived from, with the exception of the few hand-migrated packages
listed above. The migrated releases follow the naming convention
<release>-iostream-<number>.
Since all code needs to be checked out and migrated, and all binaries
are built and kept for validation purposes, the migration builds tend
to be quite big. We therefore keep them in /nfs space for now.
To access a migration build you need to redirect your BFDIST
to this directory:
$ setenv BFDIST /nfs/babar/CompMgt
Do this before doing anything else. After that, you can use
srtpath and newrel etc. as you are used to.
The most recent migrated release is 14.5.2-iostream-1.
14.5.2-iostream-1
The set of extra tags, relative to its 14.5.2 base is:
BdbAdminTools V01-00-06 (Release uses V01-00-04)
BdbClusteringServer V01-01-02 (Release uses V01-01-01)
BdbEvent V03-00-26 (Release uses V03-00-25)
BdbUtil V02-01-00 (Release uses V02-00-00)
BunchT0 V01-00-10 (Release uses V01-00-07)
CLHEP V01-06-07 (Release uses V01-06-06)
EidData V00-04-00 (Release uses V00-03-00)
EmcSrcCalApps V00-02-18 (Release uses V00-02-14)
IOStreamUtils V00-05-04 (Release uses V00-03-01)
OdfCommon V00-07-00 (Release uses V00-06-11)
OepBuffer V00-02-00 (Release uses V00-01-01)
SoftRelTools V00-16-40-01 (Release uses V00-16-40)
The output of the migration process can be found here:
/nfs/babar/CompMgt/releases/log/IOSMigrationBuild-14.5.2-cal80.log.gz
Note that the actual migration was run on cal80, currently a
RH9 machine. (See below why that is necessary.)
The two standard builds were done on Linux24RH72 and SunOS58 and their
output can be found here:
Linux24RH72_i386_gcc2953:
/nfs/babar/CompMgt/releases/log/bldlnx09-14.5.2-iostream-1.log.gz
SunOS58_sparc_WS6U1:
/nfs/babar/CompMgt/releases/log/shire03-14.5.2-iostream-1.log.gz
I was planning to discuss the remaining errors in these builds
individually here.
Validation Tests
14.5.2-iostream-1
This section still being compiled.
Building against a migrated release
To set up your own test release based on a migrated release,
e.g., 14.5.2-iostream-1, follow these steps:
$ setenv BFDIST /nfs/babar/CompMgt
$ srtpath 14.5.2-iostream-1
$ newrel -t 14.5.2-iostream-1 14.4.2-iostream-1.test
$ cd 14.4.2-iostream-1.test
At this point you can add your own unmigrated packages. For instance:
$ addpkg BetaMiniUser
There is one snag, which is that the migration tools need sed
4.0.5 or later, while RH72 and SunOS58 ship with earlier
versions. So for now you will have to make a short excursion to a RH9
or RHEL3 machine to run your own migration. After that you go back to
the platform you want to build on.
$ ssh noric-new
$ setenv BFDIST /nfs/babar/CompMgt
$ cd 14.5.2-iostream-1.test
$ srtpath
$ IOSMigrateAll
$ exit
At this point you can build your migrated code. The only special
thing is that you need to supply the flag STD_IOSTREAMS=1 on
the gmake command line.
$ gmake STD_IOSTREAMS=1 BetaMiniUser.all
This should get you a functional BetaMiniApp. If it doesn't,
please let me know.
In the same manner, you should be able to migrate any code that has
been kept outside releases (your analysis XyzUser package,
for instance). We will be very happy to help with any problems you
might find.
Page author:
Rainer Bartoldus
| Last update: 13-May-2004 |
Expiry date: 31-Dec-2004 |
|
