One of Boost Geometry (aka GGL) users, Mark, reported that he can not compile his program using the library with GNU C++ compiler from XCode. The compiler throws mysterious complain of a very low-level nature of C++ programming language:

Expected unqualified-id before 'do' in
/usr/local/include/boost_1_42_0/boost/geometry/geometries/concepts/check.hpp

Thanks to follow-up by Stjepan we quickly know who to blame for that. It is XCode header AssertMacros.h. It even might be one of public headers from development package of XNU, the Mac OS X kernel, what’s even more fun.

What actually happens that causes the problem?

Boost Geometry defines function template for concept checking:

template <typename Geometry>
inline void check()
{
    detail::checker<Geometry, boost::is_const<Geometry>::type::value> c;
    boost::ignore_unused_variable_warning(c);
}

Apple XCode defines macro using exactly the same name as the function check. The C++ preprocessor, which operates before compiler, substitutes the name check with content of the macro. For the Boost Geometry function check it means that a pile of garbage is injected in place were the function name is expected:

template <typename Geometry>
inline void do { if ( __builtin_expect(!(), 0) ) { DebugAssert('?*?*',
0, "Third Party Client" ": " "", 0, 0, "/usr/local/include/boost/
geometry/geometries/concepts/check.hpp", 181, (void*)0); } } while ( 0 )
{
     detail::checker::type::value> c;
     boost::ignore_unused_variable_warning(c);
}

Obviously, it makes compiler to give up to instantiate the check function from the template and to compile it properly.

C/C++ macros are evil, however, not by design but by insanity of programmers. Every macro defined in a public C/C++ header, should be defined using as unique as possible, but still usable name. I wish Apple folks designed their C/C++ macros as unique as they make their hardware products, even if made in China eventually. This particular macro that caused the problems discussed here, could be named to APPLE_XNU_CHECK and life would be easier. Or, given the fact that almost 3000 files using these identifiers live in Boost C++ Libraries only, I probably should say: life would be more productive, efficient and cheaper.

By the way, it’s a known problem @ Boost and it looks Boost Folks are trying to figure out best solution. See ticket #2115 – Avoid bad Apple macros.

…to be continued

By the way, I crafted AX_LIB_LIBKML macro for Autoconf. This macros checks for headers and libraries of specified version (or newer) of Google libkml library and defines compilation and linking flags.

I submitted the macro to GNU Autoconf Archive. It is the new incarnation of well-known autoconf-archive.cryp.to. Peter Simons announced not long time ago that

The archive has moved to Savannah: http://www.nongnu.org/autoconf-archive/. Version 2009-04-26 was the last to be released at autoconf-archive.cryp.to.

Happy detecting libkml!

A: The lesson is I ought to get things right the first time.
B: The issue with const method is that if you want to add lazy loading later, it can cause problems
C: GDAL is rather painful to use with const correct code, unfortunately :(
B: The solution is obvious: don’t write const correct code

Who’s right then, A or B?

I recall another motto from #gdal channel that sounds like “when unsure, do nothing” which has the following rationale:

especially when I realize afterwards that I’ve f**cked things because I neglected to follow the motto

Remembering these recommendations, it’s pretty clear why the const-mess in GDAL has happened. I’d conclude paraphrasing the motto this way:

I’ve f**cked things because I neglected to make a decision.

Now, poor GDAL beginner deadpickle, trying to find out (it’s me the evil) why compiler complains about his not-that-bad-written code, wandered to find and ask C gurus @ comp.lang.c and got the problem explained by Malcolm who wrote:

The problem is that, when C was first developed, there was no const keyword. So strings literal, which are constant, had to be non-const for backwards compatibility. This means that lots of programmers get lazy and omit the const, even from functions which don’t modify their string arguments. (There are also some subtle problems with const which means that this isn’t always a case of pure laziness). So a sort of solution is to discard the const qualifiers. However this is perpetuating the problem in your own code.

The motto stays in contradiction to a well-known best practice of const correct sooner than later. It’s way easier and cheaper to remove const-correctness once it turns out it does not express properly the actual design and contract than to apply it to existing codebase. Sometimes, the latter is even not possible making things f**cked up twice, in existing code base and in client’s code.

At 4:30, I am going to be interviewed for FLOSS Weekly.
The chat is here:
http://irc.twit.tv/
The video is here:
http://live.twit.tv/
Should be going on some time around 4:30 EST.

It’s on now.

UPDATE: FLOSS Weekly 111: CMake archived audio podcast

A few words about GIS-Lab from their website:

GIS-Lab – informal non-commercial community of GIS/RS specialists, we grow ourselves and help grow others.

GIS-Lab exists since April 2002 as an independent online resource specializing in geographic information systems (GIS) and remote sensing (RS). At present, the site is primarily oriented towards Russian-speaking GIS community, however, we do our best to translate as many materials as possible into English.

The GIS-Lab is the very first blog in Russian language syndicated with the Planet OSGeo, what makes the planet yet more international geo-caffee.

I checked Well-Known-Binary output as returned by the SqlGeometry method STAsBinary(). Here is a small test program written in C#:

using System;
using System.Linq;
using Microsoft.SqlServer.Types;
namespace SqlGeometryEmpty
{
  class Test
  {
    static void Main(string[] args)
    {
      foreach (string type in
         Enum.GetNames(typeof(OpenGisGeometryType)))
      {
        string wkt = type.ToUpper() + " EMPTY";
        SqlGeometry geom = SqlGeometry.Parse(wkt);
        byte[] wkb = geom.STAsBinary().Buffer;
        string wkbhex = string.Join("",
          wkb.Select(
            b => b.ToString("X2")).ToArray());

        Console.WriteLine("{0}\n{1} ({2} bytes)\n",
          wkt, wkbhex, wkb.Length);
      }
    }
  }
}

The first observation is that WKB of EMPTY geometry for all types is returned as a a slightly different binary. All the binary forms are truncated to nine bytes. The first byte indicates endianness as expected. The second chunk of four bytes indicate geometry type. It is exactly as defined in OGC specifications. The third chunk of remaining four bytes are set to Zero and seem to play a role of size specifier: number of points in LINESTRING or number of rings in POLYGON, number of points in MULTIPOINT, and so on. This makes another observation that WKB for EMPTY is reported as a collection of primitive components.

The difference in binary of WKB of EMPTY geometry I mentioned is in that the actual type of input geometry is preserved, so there seems to be no implicit translation to geometry of some other type.

So far so good but not for too long. In fact, SqlGeometry implicitly casts POINT EMPTY to MULTIPOINT EMPTY geometry with the WKB of the following form (in hex):

010400000000000000

Here is complete output of the test program above:

POINT EMPTY
010400000000000000 (9 bytes)

LINESTRING EMPTY
010200000000000000 (9 bytes)

POLYGON EMPTY
010300000000000000 (9 bytes)

MULTIPOINT EMPTY
010400000000000000 (9 bytes)

MULTILINESTRING EMPTY
010500000000000000 (9 bytes)

MULTIPOLYGON EMPTY
010600000000000000 (9 bytes)

GEOMETRYCOLLECTION EMPTY
010700000000000000 (9 bytes)

A word about how PostGIS behaves. PostGIS reports GEOMETRYCOLLECTION EMPTY, regardless of actual type of input EMPTY geometry. It is in hex form:

010700000000000000

Generally, there is not many choices of how to report EMPTY geometry in clear and usable way and a form of collection with size equal to Zero seems to be the most appropriate choice. POINT EMPTY reported with type set to POINT (010100000000000000) would be ambiguous as feels like truncated or invalid form of POINT(0 0), especially in programming languages like C where native dynamic allocated arrays do not carry information about their size. IOW, geometry type is not enough information to process binary form of POINT EMPTY properly.

Reporting EMPTY geometries as a collection is a useful convention that seems to work well. PostGIS behaves about it in the very consistent manner reporting one type for all empties. SqlGeometry, so SQL Server, forces programmers to write a few more lines of code to handle all the possible cases. Yet another original exotic solution from Microsoft.

Consistent API is a bless!

Update: consistent specification of interface is even better.

It is:

• Chaipat Nengcomma posts content that a part of Thai OSGeo local chapter about FOSS4G distribution in Thailand
• OTB Team developing the Orffeo Toolbox – a library of image processing algorithms developed by CNES in the frame of the ORFEO Accompaniment Program.

Welcome to the Planet OSGeo!

Update: Thanks to Hugo from Nabble for importing all archives of the ggl mailing list.

The main motivation is that it simplifies development of experiments in case one needs version control or complete disconnection from SVN trunk for some period. Thanks to git-svn, it is possible to push changes back to the trunk.

I outlined the process of maintaining GDAL trunk using Git in the Wiki article Using Git To Maintain GDAL Workflow.

The synchronization is not a time consuming process at all but even that I hope to make it automatic process in near future. First, I have to ship my little personal server to a remote data centre and I’m hoping to do it next week. Lucky bastard going to bask in the warm sun of Portugal :-)

Quickbook is a textual format, it feels quite similar to AsciiDoc or some sort of Wiki dialect but dedicated for documenting C++ programming. It is extremely easy to grasp while drinking a single short coffee.

Anyway, it seems it is going to be a quite a book after all elements of Boost.Geometry are documented. One of the challenge I’ve found is to collect all bits necessary to document C++ concepts defined by Boost.Geometry. Unfortunately, Doxygen is not an ideal tool for this purpose, so current version of the documentation lacks of some sections of concepts description. So, I have to dig the source code to find out formal definitions and details of valid expressions and semantics.

Another challenge related to concepts is to find best way to structure their documentation. I started to browse documentation of existing Boost libraries looking for examples and what I found is that there is no best example. Various libraries document concepts in very different way.

A concept is a set of requirements consisting of valid expressions, associated types, invariants, and complexity guarantees

– David Abrahams, Generic Programming Techniques

For example, neatly Boost.Fusion documents concepts with Quickbook, though some elements seem to be omitted. Boost.Graph doesn’t document with Quickbook, looks good, but some details are missing to me, for instance, titles in headers of tables saying what is what is return type and pre-/post-condition for valid expressions, etc. Documentation of Boost.IOStreams concepts sound well. On the other hand, Boost.GIL is an example of why Doxygen should not be used to document concepts of a C++ library.

It looks to me the old good Standard Template Library Programmer’s Guide at SGI is still a best and most complete example of how C++ concepts should be documented.

Given these experiences, I started to think of a way to improve the way concepts are documented within Boost. I believe it would be a good idea to have predefined block for concept in Quickbook. Something along these lines:

[concepttype [Point Concept]
  [this is a concept for 0-dimensional geometry]
  [notation
    [term 1] [description 1]
  ]
  [refinement [concept 1] [concept 2]]
  [associated
    [type 1] [description 1]
  ]
  [expressions
    [name 1 [expr 1]
      [type requirement 1] [return type 1]
  ]
  [semantics
    [name 1 [expr 1]
      [precondition 1] [semantic 1] [postcondition 1]
  ]
  [complexity [...]]
  [invariants
    [invariant 1] [description 1]
  ]
  [models [model 1] [model 2]]
  [notes
    [ note 1] [ note 1]
  ]
  [seealso ...]
]

I posted my proposal to boost-docs list explaining the motivation in details. It’s an interesting experience of a C++ documentation craftsman, anyway. (BTW, Daniel James just announced Quickbook port to Spirit 2.)