[xplc-general] example code

[Pierre Phaneuf]

In the current CVS, I added a pair of examples: a module and a program
using the module.

These are the very simplest, and other from a few platform-specific
optional optimizations, can be safely lifted into user code (the
Makefiles are also separate, so that you can lift them too!).

Some people were looking at the unit tests and would either be writing
pretty weird code (because the unit tests do pretty weird stuff to have
a carefully controlled test environment sometimes) or would be pretty
confused (understandable!).

This should help these people.

Coming soon, some examples using categories (critical for the classical
"plugin" type of use).

[Stéphane Lajoie]

Post by Pierre Phaneuf
In the current CVS, I added a pair of examples: a module and
a program using the module.

Sorry to be a license nazy again, but these should really be public domain
or something just as free. People should be able to cut-and-paste code out
of there without worry.

Post by Pierre Phaneuf
These are the very simplest, and other from a few
platform-specific optional optimizations, can be safely
lifted into user code (the Makefiles are also separate, so
that you can lift them too!).

What are those platform-specific optimizations? It all seems very
platform-agnostic to me...

Except that there isn't any VS project files. I'd like to make some but I
don't know where they should go (well I do know exactly the right place to
put them, but I don't know which wrong place you will make me move them to
:)). So tell me.

One nitpick: simple-module-user/simple.cpp sees getSimpleComponent in its
global namespace, but it only needs SimpleComponent_CID. I'm pretty sure
nobody would call that function by accident (especially considering it
wouldn't even link) but I still think it might be better to separate the
class ids and the factory functions in two separate header files: one meant
for external consumption and the other with internal implementation details.

More nitpick: the Makefile should not be referring to ../.. or ../../include
or stuff like that. I think it would be better if it assumed the correct
version of xplc is installed on the system. That way, people lifting entire
examples into their own projects could use the Makefile as is without
needing to include the whole xplc source (which would be a stupid thing to
do, but people are known to be stupid sometimes). Of course most people
would write their own makefiles (or use automake/autoconf), but if you're
going to provide one it should be a perfect example.

[Pierre Phaneuf]

Post by Stéphane Lajoie
Sorry to be a license nazy again, but these should really be public
domain or something just as free. People should be able to
cut-and-paste code out of there without worry.

Yeah, that's true. I'll do that (I own the full copyright for the examples).

Post by Stéphane Lajoie

Post by Pierre Phaneuf
These are the very simplest, and other from a few platform-specific
optional optimizations, can be safely lifted into user code (the
Makefiles are also separate, so that you can lift them too!).

What are those platform-specific optimizations? It all seems very
platform-agnostic to me...

They're optional! :-)

I was referring to using a linker script to restrict the exportation of
symbols (like a DEF file would on Win32, I think).

Post by Stéphane Lajoie
Except that there isn't any VS project files. I'd like to make some
but I don't know where they should go (well I do know exactly the
right place to put them, but I don't know which wrong place you will
make me move them to :)). So tell me.

How many dozens of files does that involve? :-)

If these were a single file, I'd put them right in the specific example
directory. If they're a bunch of files, well, I suppose they'd still
have to go there...

The idea is that you could take the whole directory.

Post by Stéphane Lajoie
One nitpick: simple-module-user/simple.cpp sees getSimpleComponent in its
global namespace, but it only needs SimpleComponent_CID. I'm pretty sure
nobody would call that function by accident (especially considering it
wouldn't even link) but I still think it might be better to separate the
class ids and the factory functions in two separate header files: one meant
for external consumption and the other with internal implementation details.

Yeah, I thought about it for a second, and didn't do it, but it's a good
idea.

Post by Stéphane Lajoie
More nitpick: the Makefile should not be referring to ../.. or ../../include
or stuff like that. I think it would be better if it assumed the correct
version of xplc is installed on the system. That way, people lifting entire
examples into their own projects could use the Makefile as is without
needing to include the whole xplc source (which would be a stupid thing to
do, but people are known to be stupid sometimes). Of course most people
would write their own makefiles (or use automake/autoconf), but if you're
going to provide one it should be a perfect example.

You're right again. I still wanted it to be able to at least build
inside of XPLC without installing it, but I know what I'll do: I'll have
xplc/examples/Makefile pass in CPPFLAGS and LDFLAGS on the command-line
when calling "make" in the subdirectories.

It's a bit annoying, because it breaks just running "make" inside those
directories, though...

I'll figure out something.

[Stéphane Lajoie]

Post by Pierre Phaneuf

Post by Stéphane Lajoie
Except that there isn't any VS project files. I'd like to make some
but I don't know where they should go (well I do know exactly the
right place to put them, but I don't know which wrong place you will
make me move them to :)). So tell me.

How many dozens of files does that involve? :-)
If these were a single file, I'd put them right in the
specific example
directory. If they're a bunch of files, well, I suppose they'd still
have to go there...
The idea is that you could take the whole directory.

It would be one file in examples/ and one in each of examples/* where a
target has to be generated (currently there are two).

If you want to be a nazi and force me to segregate them in a VisualC++
subdirectory, tell me now. I can barely endure doing something stupid like
that, but having to move (and rewrite) perfectly good files is beyond me, so
I need to know right away if it is going to happen at all.

[Pierre Phaneuf]

Post by Stéphane Lajoie
It would be one file in examples/ and one in each of examples/* where a
target has to be generated (currently there are two).
If you want to be a nazi and force me to segregate them in a VisualC++
subdirectory, tell me now. I can barely endure doing something stupid like
that, but having to move (and rewrite) perfectly good files is beyond me, so
I need to know right away if it is going to happen at all.

Nah, *one* at the top level of the examples and *one* in each directory
is no worse than the Makefiles. I just seem to remember no ends of
.ncbs, .dsps, .dsws, .whatever-the-hell-else...