Today I am happy to say that it all finally clicked into place for me. And, in hindsight, I went about understanding and learning DocBook using an incorrect approach – basically back-to-front. I tried to understand DocBook, then the transformation layer and then get to XSL FO. No.. bad idea. If you’re trying to learn DocBook and get a good understanding of how everything works, you need to learn in order:

• XML Namespaces – Just kinda know what they are about and how to import them and use them.
• XSL FO – Learn about blocks, general attributes and properties, documents and flows.
• XSLT – Figure out how XSLT works, the templates, callbacks, “variables”, etc. Understand that it’s not a procedural language and not a see-this-replace-with-that kind of engine. Understand that you’ll actually building a DOM.
• DocBook – Get acquainted with the allows tags, the hierarchy and what they’re used for in the document.
• DocBook XSL – The stylesheets you can get which perform XSLT transformations from DocBook schema into FO schema, for example.

Still, it’ll take some time if you’re coming in as a newbie. Speaking as a programmer, I found it really different.

So, what the heck was the problem? I fiddled with a custom typemap.dat and made sure the xsd__long was defined as an int64_t (‘cos it is on my platform) and I even found some suggestions on the Internet to use “-e” when compiling using soapcpp2. Nada.

That’s when I started debugging gSOAP – as I have been doing continuously the last two weeks – and I traced the problem all the way back to a function inside stdsoap2.cpp called “soap_s2LONG64″. This function is responsible for string to long conversion. Now the first thing I noticed is that it’s possible for the entire function to be completely empty because almost all of it is conditional with a lot of #ifdefs. I double checked this by having a look at my compiled assembly and sure enough it was completely empty. There was no way for this function to ever succeed.

What had I done wrong? Well I had included the gsoap code directly into my build – my makefile – and I wasn’t building it as a separate library. What I had failed to notice though is that the stdsoap2.h needs config.h to determine which functions are available on the system. Some of these functions are the very ones used within soap_s2LONG64. Since there was no detection and definition of the defines, there was no real body to the function. That’s why it was happening.

Of course, I just added the checks into autoconf and made sure that stdsoap2.h’s include directive for the config.h file was pointing to the right place. Viola. It was working like a charm.

In summary: If you’ve included stdsoap2.cpp into your build, then you need to define which string to long conversion functions are in your system. You can do with this with your compilation command (g++ -DHAVE_STRTOLL) or define it just before you include stdsoap2.h in your code. Of course, autoconf makes it a lot easier. It’s up to the build system you’re using. If you’re doing it manually, try defining HAVE_STRTOLL or HAVE_SSCANF.

I needed a nice support architecture where, if someone sent an email to support, it would get pulled into a system, processed, etc and everything would happen to give the person a fantastic support experience – if there is such a thing. This seems to do it.

It’s also incredibly easy to setup and fast to get going. There’s basically no learning curve. The entire setup, including creating an email address on my side, took about 10-30 minutes. Support system done. So far so good.

Most people won’t have the problem I’m having since I think it might work out-of-the-box for a “common” system like Linux or their package management system has installed it for them. For me, however, I wanted to do two thing:

• Add some extra compiler flags to specify the correct CPU architecture
• Make sure the Sun linker was correctly detected instead of boost using the g++ frontend to do the linking. The command line options are incorrect.

Seems simple enough? Well the problem when you roll-your-own build systems like this is that it differs from the standard conventions. So you can’t use any knowledge or experience to fix this. You have to suddenly learn something new. This shouldn’t be the case for a standard library.

For example, just overriding CPPFLAGS, CFLAGS or CXXFLAGS on the command line had absolutely no effect despite the fact that the configure script said it would. And where do you set the linker easily … ? Well, you cant.

However, I managed to combine knowledge I acquired from several different sites to get this working.

http://www.pion.org/files/pion-platform/common/doc/README.solaris
http://blogs.sun.com/sga/entry/how_to_build_boost_1
http://shoaibmir.wordpress.com/2009/08/12/building-boost-under-solaris/

Each of which has some useful piece of information. And so I did the following… I made sure the prefixes and everything were set up.


./configure --prefix=<path> LDFLAGS="-L<path>" CPPFLAGS="-I<path>"


(Not sure of the CPPFLAGS or LDFLAGS were honoured, I didn’t check.) And then this generates a “user-config.jam” file in the top directory. I modified mine as follows:


# Boost.Build Configuration
# Automatically generated by Boost configure

# Python configuration
using python : 2.3 : /usr/sfw ;


If you don’t specify the CPU architecture, you get warnings from the assembler (as) about the opcode “cas” being incorrect for the architecture – applicable to v9’s instead of v8’s ‘cos “cas” is atomic on v9’s. “(Requires v9|v9a|v9b; requested architecture is v8.)”. And then ….


make


viola. Easy, huh? No …. not at all. The above represents several hours of work. I’m not even sure that it’s the “correct” way to do it.

In the end I’ve discovered two libraries which I find useful:

• Xerces-C++ which is a part of the Apache project. It’s a fully implemented, validating XML parser which supports DOM, SAX and SAX2 APIs. It’s very good. It’s very big. It does it all.
• If you don’t care about completeness and you just want to get the job done with your XML, then I’d recommend this small, simple, cross-platform, free and fast C++ XML Parser which is basically a header file and an implementation file. It’s quick and easy to use. Initially I was attracted to it because the API was almost exactly the same as the convenience library I’d used in my previous work. However, I didn’t end up using it because it really just cares about getting the job done and extracting or building XML. So other nice things like error codes, etc have been neglected. For example, the inability of the parser to parse a file will result in the parser exit()’ing the entire application. So I couldn’t use this in an end-user product. Otherwise, great for RAD. The author will also re-license the code to you if you need a BSD license.

Also, from what I can see, my entire current business costs are tax deductible to approximately 150% of the value. It turns out that South Africa offers a huge tax incentive for R&D in the whole Intellectual Property space. The definition of R&D is broad enough to include the salaries of software developers. Awesome. This incentive is further sweetened for some countries outside of the Republic – including the UK, China, Belgium and others – because they can then claim deducations from both South Africa and their own governments. It’s interesting and complicated stuff.

• I actually have quite a lot of work at the moment doing an integration project. This is taking up all of my time.
• I haven’t yet received access to the Sun EZQual virtual lab to compile the code on a SUN machine.

I’m eventually going to need a SUN machine of my own but then that brings in the problem of cost and of hosting. Ah well….

Of course, I’m sure Microsoft and others are equally as supportive. After all, they’re all fighting for the same space. I’ll investigate what it takes to achieve a Microsoft partnership.

It’s quite pleasant to be able to walk across the road and visit the mall. I can do my daily shopping during my lunch break. It has a branch of the Virgin Active gym to which I have a membership. So my plan for the next couple months is to work and work out. After about 5 years of sitting in a chair doing software development for my previous company, I have a lot of health and fitness to recover.