Archive for category C++ Discoveries and Notes

Gtkmm 3.0 in Ubuntu 11.04

Lately I’ve been writing a lot of codes using gtkmm 3.0. The latest stable branch is 2.4, but this is based on GTK+ 2… and I really want to use GTK+ 3. Why? Because GTK+ 3 uses cairo for it’s native drawing API, and cairo is sweet. gtkmm uses cairomm, which is even sweeter. So here are my notes on getting gtkmm-3 built and installed for Ubuntu 11.04. I’ve written a shell script to do all the work, but I’ll go through it section by section to explain what’s going on.

Setup

Traditionally /usr/ is used for normal system stuff /usr/local is for experimental stuff (it’s essentially the same as /usr but it makes it easy to find and remove stuff after it breaks your system). However, since I originally was developing with the unstable Gtkmm branch in Ubuntu 10.04, which didn’t even have a package for GTK+ 3 in the repositories, I started installing things into my home directory… since it’s just for testing anyway. Therefore, I create a directory $HOME/Codes/devroot (for development root filesystem) where I install all the “unstable” packages I’m using, or where I practice-install the programs/libraries I’m writing.

I also make a directory $HOME/Codes/cpp/gnome where I download all the source tarballs and do the building.

1
2
3
4
5
6
7
8
9
10
11
12
13
#!/bin/bash
cd $HOME
 
export BASE=$HOME/Codes/devroot
export PATH=$BASE/bin:$PATH
export LD_LIBRARY_PATH=$BASE/lib:$LD_LIBRARY_PATH
export PKG_CONFIG_PATH=$BASE/lib/pkgconfig:$PKG_CONFIG_PATH
export XDG_DATA_DIRS=$BASE/share:$XDG_DATA_DIRS
export ACLOCAL_FLAGS="-I $BASE/share/aclocal $ACLOCAL_FLAGS"
 
mkdir -p $BASE
mkdir -p Codes/cpp/gnome
cd Codes/cpp/gnome

Next I export some variables containing the versions of the unstable packages I’m using. This is so that I can quickly update the script for future installations and things.

15
16
17
18
19
20
export MM_COMMON_VER=0.9.5
export GLIBMM_VER=2.28.1
export ATKMM_VER=2.22.5
export PANGOMM_VER=2.28.2
export CAIROMM_VER=1.1.10
export GTKMM_VER=3.0.1

Then I download all the source tarballs

22
23
24
25
26
27
wget http://ftp.acc.umu.se/pub/GNOME/sources/mm-common/0.9/mm-common-$MM_COMMON_VER.tar.gz
wget http://ftp.acc.umu.se/pub/GNOME/sources/glibmm/2.28/glibmm-$GLIBMM_VER.tar.gz
wget http://ftp.acc.umu.se/pub/GNOME/sources/atkmm/2.22/atkmm-$ATKMM_VER.tar.gz
wget http://ftp.acc.umu.se/pub/GNOME/sources/pangomm/2.28/pangomm-$PANGOMM_VER.tar.gz
wget http://ftp.acc.umu.se/pub/GNOME/sources/gtkmm/3.0/gtkmm-$GTKMM_VER.tar.gz
wget http://cairographics.org/snapshots/cairomm-$CAIROMM_VER.tar.gz

And extract them all into $HOME/Codes/cpp/gnome (currently PWD).

29
30
31
32
33
34
tar xvzf mm-common-$MM_COMMON_VER.tar.gz
tar xvzf glibmm-$GLIBMM_VER.tar.gz
tar xvzf atkmm-$ATKMM_VER.tar.gz
tar xvzf pangomm-$PANGOMM_VER.tar.gz
tar xvzf gtkmm-$GTKMM_VER.tar.gz
tar xvzf cairomm-$CAIROMM_VER.tar.gz

Then we start installing the packages in the appropriate order. There are a few ugly things that we have to do in the process though.

36
37
38
39
40
41
42
43
44
45
cd mm-common-$MM_COMMON_VER
./configure --prefix=$BASE
make -j6
make install
cd ..
 
cd glibmm-$GLIBMM_VER
./configure --prefix=$BASE
make -j6
make install

The first ugly thing is that the glibmm package doesn’t install the doctool perl script like it should… so we have to do that manually:

46
47
mkdir -p $BASE/share/glibmm-2.4/doctool/
cp docs/doc-install.pl $BASE/share/glibmm-2.4/doctool/

Then we continue installing the libraries

48
49
50
51
52
53
54
55
56
57
cd ..
 
cd atkmm-$ATKMM_VER
./configure --prefix=$BASE
make -j6
make install
cd ..
 
cd pangomm-$PANGOMM_VER
./configure --prefix=$BASE

The second ugly thing we have to do is move libfreetype.la to where libtool can find it. I’m not sure why it can’t find this specific library but for whatever reason, even after setting LD_LIBRARY_PATH it always looks in /usr/lib. So I just pretend like no ones watching and create a symlink.

58
sudo ln -s /usr/lib/x86_64-linux-gnu/libfreetype.la /usr/lib/

And everything after that goes pretty normally.

59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
make -j6
make install
cd ..
 
cd cairomm-$CAIROMM_VER
./configure --prefix=$BASE
make -j6
make install
cd ..
 
cd gtkmm-$GTKMM_VER
./configure --prefix=$BASE
make -j6
make install
cd ..

No Comments

HTML Documentation with Equation Numbers (Referencing an External PDF Document with Doxygen’s HTML Documentation)

So, anyone who uses Doxygen to document their code knows that it’s pretty much the most amazing thing ever. Seriously, it’s awesome. One cool thing about it is the ability to reference external documentation. For instance, if you use a library in your code and you want to include the library’s documentation with your own. However, let’s say that (hypothetically of course) you’re an academic… and the code you write implements some theoretical design or model. In that case, you may actually want your documentation to reference a paper, or a report that you’ve written. Perhaps, even many such papers or reports.

The Problem

In particular, let’s say that you’re a grad student, in the process of writing a paper (and of course, you used LaTex… because, well, why wouldn’t you?) and you go and write some code to simulate or demonstrate some elements of that paper. In that case, some of your functions may implement certain equations. Some of your classes (if it’s object oriented) may implement certain models. For an example, lets say this is your paper:

Let’s also assume that you’ve been good, and have been documenting your code with Doxygen. Let’s say you had some c++ class that implemented your model and it’s definition looks something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
/**
 *  file       CTheoreticalModel.h
 *  author     Joe Author (jauthor@institute.edu)
 *  date       Apr 17, 2010
 *  brief      Definition file for CTheoreticalModel class
 */
 
#ifndef CTHEORETICALMODEL_H_
#define CTHEORETICALMODEL_H_
 
 
/**
 *  brief  Theoretical Model derived in section 2, on page 1
 *
 *  This is a detailed description of the model
 */
class CTheoreticalModel
{
    private:
        double    m_alpha;    ///< [parameter] defined in equation 2.1
        double    m_beta;     ///< [parameter] defined in equation 2.2
 
    public:
        /**
         *  brief      Construct a new model using the given parameters
         *  param[in]  alpha   [parameter] defined in equation 2.1
         *  param[in]  beta    [parameter] defined in equation 2.2
         */
        CTheoreticalModel( double alpha, double beta );
 
 
        /**
         *  brief      calculates [some property] by implementing algorithm 2.1
         *              on page 1
         *  return     [some property]
         */
        double algorithmA();
 
 
        /**
         *  brief      updates the model by [some parameter] according to the
         *              dynamics of equation 2.4
         *  param[in]  gamma   [parameter] defined in equation 2.3
         */
        void equationB( double gamma );
 
 
        /**
         *  brief      tests [some parameter] against the model; implements
         *              equation 2.6
         *  param[in]  theta   [some parameter] defined by equation 2.5
         */
        bool testC( double theta );
};
 
#endif /* CTHEORETICALMODEL_H_ */

Then the html documentation that doxygen will generate will look like this:


Now let’s say that you talk to your advisor and he suggests that maybe section 2 should come after section 3. Moreover, you add a bunch of content to section 1 so now all of the code for this model is on page five. So then you end up with this:

So now you have to go back and change all of the equation numbers and page references in your code. But wait, when we wrote our document we “label{}“ed all of our equations, algorithms, and sections. Wouldn’t it be cool if we could just reference those in the comments? Doxygen exposes latex’s math mode for us to document inline equations. It uses latex to render the equations, and then uses dvipng to turn those into png images. Moreover, latex has the xr package, which allows us to reference labels from other documents. Lastly, the “ref{}” command is valid inside math-mode. So we have all the tools we need, but there is one slight problem. In order to use the xr latex package, we need to include the “externaldocument” command in the header of the document.

The solution

Now here’s the fun part. When Doxygen renders all of the equations, it does so by generating a single latex source file called “_formulas.tex“. We don’t have explicit access to modify the preamble of that source file, but we are allowed to add optional packages to the list of what is included. We do that by modifying the “EXTRA_PACKAGES” line of the doxyfile. For instance, if we edit the doxyfile like this:

1
2
3
4
5
6
...
# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX 
# packages that should be included in the LaTeX output.
 
EXTRA_PACKAGES = amsmath xr amsfonts
...

then when doxygen generates _formulas.tex it will include in the preamble a list of includes like this

1
2
3
    usepackage{amsmath}
    usepackage{xr}
    usepackage{amsfonts}

Note that Doxygen tokenizes the list of packages (parses it) at whitespace, and then takes each token and wraps it with “usepackage{}”, inserting it into the header. We can hijack this method of input by making EXTRA_PACKAGES variable like this

1
2
3
...
EXTRA_PACKAGES = amsmath xr}externaldocument[paper-]{dummy}% amsfonts
...

Then the preamble of _formulas.tex will look like this

1
2
3
4
    usepackage{amsmath}
    usepackage{amsfonts}
    usepackage{xr}externaldocument[paper-]{dummy}%}
    usepackage{hyperref}

Note how we use a comment character (percent) to comment out the closing bracket that doxygen put’s around our ‘package’. Now we have an extra command in our preamble. If you haven’t looked up the xr documentation yet, this command means to look for a file called “dummy.aux” generated by latex. The package extracts all the labels from that file and appends “paper-” to the front of the label names. Now we can change our code documentation to look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
/**
 *  file       CTheoreticalModel.h
 *  author     Joe Author (jauthor@institute.edu)
 *  date       Apr 17, 2010
 *  brief      Definition file for CTheoreticalModel class
 */
 
#ifndef CTHEORETICALMODEL_H_
#define CTHEORETICALMODEL_H_
 
 
/**
 *  brief  Theoretical Model derived in section f$ref{paper-sec:Model}f$,
 *          page f$pageref{paper-sec:Model}f$
 *
 *  This is a detailed description of the model
 */
class CTheoreticalModel
{
    private:
        double    m_alpha;    ///< [parameter] defined in equation f$ref{paper-eqn:alphaDef}f$
        double    m_beta;     ///< [parameter] defined in equation f$ref{paper-eqn:betaDef}f$
 
    public:
        /**
         *  brief      Construct a new model using the given parameters
         *  param[in]  alpha   [parameter] defined in equation
         *                      f$ref{paper-eqn:alphaDef}f$
         *  param[in]  beta    [parameter] defined in equation
         *                      f$ref{paper-eqn:betaDef}f$
         */
        CTheoreticalModel( double alpha, double beta );
 
 
        /**
         *  brief      calculates [some property] by implementing algorithm
         *              f$ref{paper-alg:SomeAlgorithm}f$ on page
         *              f$pageref{paper-alg:SomeAlgorithm}f$
         *  return     [some property]
         */
        double algorithmA();
 
 
        /**
         *  brief      updates the model by [some parameter] according to the
         *              dynamics of equation f$ref{paper-eqn:SomeEquation}f$
         *              on page f$pageref{paper-eqn:SomeEquation}f$
         *  param[in]  gamma   [parameter] defined in equation
         *                      f$ref{paper-eqn:gammaDef}f$
         */
        void equationB( double gamma );
 
 
        /**
         *  brief      tests [some parameter] against the model; implements
         *              condition f$ref{paper-eqn:SomeCondition}f$
         *  param[in]  theta   [some parameter] defined by equation
         *                      f$ref{paper-eqn:thetaDef}f$
         */
        bool testC( double theta );
};
 
#endif /* CTHEORETICALMODEL_H_ */

Now all we have to do is dump dummy.aux (generated when we build the paper using latex) into the html directory where doxygen is going to build _formulas.tex and then when we make the documentation it looks like this:


Sure, all the references are images… which isn’t particularly great, but it’s a lot better than having to go in and change the labels every time we make a change to the referenced document. Whenever writing a code and a referenced document are done in parallel, this could be quite a handy trick. If you want the html document to look a little more professional, add a package that will set the font to the same as the font set by your doxygen CSS stylesheet.

If you want to play around with the files used in this post, pick them up here: dummy.7z. Create the latex document with the following command.

1
latex dummy.tex

Then copy dummy.aux into the html directory.

1
cp dummy.aux html/

Then run doxygen

1
doxygen doxyfile

No Comments

Instanciate Objects of Unknown Type from Their Parent Interface

This is based on my previous two posts on Static Interfaces in C++ and Keep Track of and Enumerate All Sub-classes of a Particular Interface. The idea is that I want my code to be extensible in the feature without requiring any re-writing of the current code base. The code base operates on generic objects via their interfaces, so as long as newly-coded classes properly extend those interfaces, the program should know how to handle them. The problem is, how can we write the program in such a manner that a user interface can enumerate available options for implementations of a particular interface, and how can we instantiate those objects?

In Keep Track of and Enumerate All Sub-classes of a Particular Interface I showed how to maintain a registry of classes deriving from a given interface, which handles the first problem, but there is a limitation in that all of these classes must provide a factory method that takes no parameters (void input). I decided that, for my project, this was not acceptable and I needed a way to define the creation parameters as part of the factory methods, whereas the creation parameters may be different for particular interfaces.

In Keep Track of and Enumerate All Sub-classes of a Particular Interface I showed how we can enforce the requirement of a static method in derived classes with a particular signature using a template interface.

In this post I will combine the two so that we can create a registry of classes that inherit from a particular interface, and provide a static factory method for creating objects of that interface, using a particular creation method signature unique to that interface. The registry will pair class names with function pointers that match the specific signature of the interface the class is being registered for.

Disclaimer: I do not claim this is the “best” way to handle this issue. This is just what I came up with. It happens to be pretty involved and overly indirect, which means it’s probably bad design. It is, however, an extremely interesting exercise in generic programming.

Prequil: the code will require these later so there they are:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/**
 *  file          RegistryTest.cpp
 *  date:      Aug 14, 2009
 *  brief:
 *
 *  detail:
 */
 
 
#include <set>
#include <map>
#include <string>
#include <iostream>
 
using namespace std;

Ok, so lets begin. First let’s define a couple of interfaces that we’re interested in.

16
17
18
class InterfaceA{};
class InterfaceB{};
class InterfaceC{};

Now we create a template class whose sole purpose is to create a per-interface typedef of the function signature that is necessary for instantiating and object of that class. Is it really possible that all sub-objects can be instantiated with the same parameters? If that’s the case, shouldn’t they all be combined into a single class that just contains that information as private members? Probably, but in my case these parameters are more like a “bare minimum” for instantiation, and then many more parameters are set by the user. It makes sense to me, I promise. If it doesn’t to you, you don’t have to use this.

19
20
21
22
23
24
template< typename InterfaceType >
class Factory
{
    public:
        typedef InterfaceType*(*Creator)(void);
};

Creator is now a typedef that aliases a function pointer that takes no parameters. Wait, isn’t that what we had before? Yes, but now we make a couple of template specializations to define the different signatures for our specific interfaces. These specializations would normally be in the file that contained the interface declaration.

25
26
27
28
29
30
31
32
33
34
35
36
37
38
/// specializations can define other creators, this one requires an int
template<> class Factory<InterfaceB>
{
    public:
        typedef InterfaceB*(*Creator)(int);
};
 
/// specializations can define other creators, this one requires an int, a
/// bool, and a char
template<> class Factory<InterfaceC>
{
    public:
        typedef InterfaceC*(*Creator)(int,bool,char);
};

Cool. Now we create a static interface that enforces it’s derivative classes to contain a static method called createNew which can be used to instantiate a new object of that interface. We can use the typedef we just created to make the function signature generic for this template (or specific to individual instantiations of it).

39
40
41
42
43
44
45
46
47
48
template<typename InterfaceType, typename ClassType>
class IStaticFactory
{
    public:
        IStaticFactory()
        {
            typename Factory<InterfaceType>::Creator check = ClassType::createNew;
            check = check;
        }
};

Still following? Good. Now we define the registry class template, which maps the class name of a derived class to a function pointer with an interface-specific signature that serves as a static factory for objects of the derived class, returning a pointer to that object of the type of the interface. See my previous post for details on this class.

49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
template <typename InterfaceType>
class Registry
{
    private:
        std::map< std::string, typename Factory<InterfaceType>::Creator > m_creatorMap;
 
 
        Registry(){}
 
    public:
 
        static Registry& getInstance();
 
 
        bool registerClass( const std::string& name,
                             typename Factory<InterfaceType>::Creator creator );
 
 
        std::set<std::string>  getClassNames();
 
 
        typename
        Factory<InterfaceType>::Creator
        Registry<InterfaceType>::getCreator(
                std::string className );
};
 
 
 
// A convient macro to compact the registration of a class
#define RegisterWithInterface( CLASS, INTERFACE )                   
namespace                                                           
{                                                                   
    bool dummy_ ## CLASS =                                          
    Registry<INTERFACE>::getInstance().registerClass(     
            #CLASS, CLASS::createNew );                               
}
 
 
 
 
 
 
 
 
 
template <typename InterfaceType >
Registry<InterfaceType>& Registry<InterfaceType>::getInstance()
{
    static Registry<InterfaceType>    registry;
    return registry;
}
 
 
 
 
 
 
 
 
 
 
 
 
template <typename InterfaceType >
bool Registry<InterfaceType>::registerClass( const std::string& name,
                        typename Factory<InterfaceType>::Creator creator )
{
    m_creatorMap[name] = creator;
    return true;
}
 
 
 
 
 
 
 
 
 
 
template <typename InterfaceType >
std::set<std::string>  Registry<InterfaceType>::getClassNames()
{
    std::set<std::string>   keys;
 
    typename
    std::map< std::string, InterfaceType* (*)(void) >::iterator pair;
 
    for( pair = m_creatorMap.begin(); pair != m_creatorMap.end(); pair++)
        keys.insert( pair->first );
 
    return keys;
}
 
 
 
 
 
 
 
 
 
 
template <typename InterfaceType >
typename
Factory<InterfaceType>::Creator
Registry<InterfaceType>::getCreator(
        std::string className )
{
    return m_creatorMap[className];
}

The difference between this and the Registry in my previous post, is that this time the registry uses the generic Factory<InterfaceType>::Creator typedef to define the function pointer. This way, that pointer is forced to have the specific signature. Sweet!

Now lets write some derived classes of those interfaces.

161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
class   DerivedA : public InterfaceA,
                    public IStaticFactory<InterfaceA, DerivedA>
{
    public:
        static InterfaceA*  createNew(){ return (InterfaceA*)1; }
};
 
 
RegisterWithInterface(DerivedA, InterfaceA);
 
 
 
class   DerivedB : public InterfaceB,
                    public IStaticFactory<InterfaceB, DerivedB>
{
    public:
        static InterfaceB*  createNew(int a){ return (InterfaceB*)2; }
};
 
 
RegisterWithInterface(DerivedB, InterfaceB);
 
 
 
class   DerivedC : public InterfaceC,
                    public IStaticFactory<InterfaceC, DerivedC>
{
    public:
        static InterfaceC*  createNew(int a, bool b, char c){ return (InterfaceC*)3; }
};
 
RegisterWithInterface(DerivedC, InterfaceC);

These classes are basically dummies, but inheriting from IStaticFactory... the compiler will enforce that they contain the static method createNew with the proper signature. Notice that InterfaceA uses the default template so the static factory in DerivedA takes no parameters, while InterfaceB and InterfaceC have specializations so the static factories in DerivedB and DerivedC have their respective parameters. Since this is just an example, the methods don’t actually create new objects they just return pointers, but in reality this is where we would use new DerivedA(...) and so on.

Well that’s it. Pretty cool huh? The compiler will enforce all this stuff for us so we can actually say to ourselves when we write new implementations months from now “If it compiles, it will be compatible.”

Lastly, here’s a little test case to run

193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
int main()
{
    DerivedA    a;
    DerivedB    b;
    DerivedC    c;
 
    InterfaceA* pA;
    InterfaceB* pB;
    InterfaceC* pC;
 
    Factory<InterfaceA>::Creator makesObjectOfA =
            Registry<InterfaceA>::getInstance().getCreator("DerivedA");
    pA = (*makesObjectOfA)();
 
    Factory<InterfaceB>::Creator makesObjectOfB =
            Registry<InterfaceB>::getInstance().getCreator("DerivedB");
    pB = (*makesObjectOfB)(1);
 
    Factory<InterfaceC>::Creator makesObjectOfC =
            Registry<InterfaceC>::getInstance().getCreator("DerivedC");
    pC = (*makesObjectOfC)(1,false,'a');
 
    cout << "pA: " << pA << "n";
    cout << "pB: " << pB << "n";
    cout << "pC: " << pC << "n";
 
    return 0;
}
Output of the Test Program

Output of the Test Program

No Comments