[Alephmodular-devel] Organizing files wrt multiple platforms

[Woody Z. I. <woo...@sb...>]

I'm finally getting around to posting some thoughts I had sent to Br'fin 
before the AM list was in place.  This is one such message.

The following is a message I sent to the M-Dev list about a year ago, 
but it seems relevant now again.  There's nothing terribly exciting or 
clever here, but it may spark some discussion.

Note that with a movement toward classes and objects, a lot of this 
material may need to be rethought, FWIW.

Woody

----- Original Message -----
From: "Woody Zenfell" <woo...@ho...>
Sent: Thursday, January 17, 2002 7:55 PM

> Personally, I'd like to see some standardization on the handling of 
> chunks
> of code that differ for different platforms.  There are currently many, 
> MANY
> ways this is done, which gets to be awfully confusing.
>
> In my code, <basefilename>.cpp contains code for both (all) platforms.
> <basefilename>_macintosh.cpp has code for the Mac OS version;
> <basefilename>_sdl.cpp has code for the SDL version.  I even tried to 
> name
> ones that only apply to the SDL version <whatever>_sdl.cpp to maintain 
> this
> convention.  A .cpp file never #includes any other .cpp file, so a 
> project
> file will incorporate the <basename>_<platform>.cpp AND <basename>.cpp 
> (if
> it exists).
>
> One (non-trivial) drawback to my approach is that elements that used to 
> be
> file-private can no longer be (if they need to be seen by both shared 
> code
> and platform-specific code).  In those cases, I made 
> <basename>_private.h
> that's intended to be #included only by one or two files.  <basename>.h
> continues to provide "externally visible" elements to the rest of the 
> code
> base.  This is still a sort of global namespace pollution, and if the
> project got big enough, we could start to have linkage problems as names
> conflict, but so far it seems to be OK.
>
> In some cases, there's like <basefilename>.cpp, that #includes
> <basefilename>_<platform>.cpp depending on preprocessor conditionals.  
> This
> lets shared code and platform-specific code keep their private elements
> private ("static").  But when managing the project files, it's somewhat
> confusing - if you compile both <basename>.cpp and
> <basename>_<myplatform>.cpp, you have problems.
>
> In other cases, there's like <basename>_<platform>.cpp, which #includes
> <basename>.cpp or <basename>_shared.cpp.  I actually like this better 
> than
> the above - it feels better having the project files choose the branch
> rather than the preprocessor.  This, like the previous one, preserves
> "privacy", but has the same multiple-definition problem.  Unfortunately,
> it's more likely to produce errors at link-time than compile-time, 
> compared
> to the above.  (Earlier errors are better.  <basename>.cpp is more 
> likely to
> compile on its own than <basename>_<platform>.cpp would be, I think.)
>
> In general, I'd prefer to see .cpp files that are #included by other 
> .cpp
> files have a different extension.  I'm sure there's one in standard use 
> out
> there for this purpose (something like ".ipp"?).  It would make it 
> clearer
> which one a project file should reference directly, and which ones will 
> get
> rolled in some other way.
>
> In still OTHER cases, there's like <basename>.cpp, which gives 
> Mac-specific
> routines, and <basename>_sdl.cpp, which gives SDL-specific routines.  I
> don't like this, although (given the CVS and project file hassles 
> involved
> with renaming something) I understand how the practice developed.  
> Still, if
> someone's going to be massively reworking this stuff, I'd prefer to see 
> this
> cleaned up while the opportunity is at hand.
>
> I'm sure there are still a couple MORE conventions used to combat this
> problem (base class/derived classes?  preprocessor conditionalization 
> within
> a single source file?), but those are all I remember off the top of my 
> head,
> and I think they're sufficient to illustrate the problem.
>
> I guess I'd prefer to see something that allows separate compilation but
> manages namespaces explicitly, like encapsulation in classes or use of 
> the
> C++ namespace construct.  But, it could be a major pain to 
> retroactively fit
> this onto existing code.  As a second choice, I might like using
> <basename>_<platform>.cpp, which #includes
> <basename>.<included-source-extension> or
> <basename>_shared.<included-source-extension>.  As a third choice, I 
> like
> the other way around (basename.cpp #includes
> basename_platform.included-source-extension).  Note that perhaps oddly, 
> I'm
> not too keen on my own scheme!  Oh well, it made sense at the time, and 
> I do
> like it better than the #include mechanisms if included files have a 
> .cpp
> extension (which, note, they did when I used my scheme).
>
> Another option (not currently used) would be to have subdirectories of 
> each
> major source directory for Mac, SDL, etc.  Shared code would live in the
> major source directory; platform-specific code would live in one of the
> subdirectories.  It might still be nice for the source files to have 
> _sdl or
> _macintosh after them, though, to make it doubly clear what file you're
> working with in your editor/build system.  I don't know whether the
> subdirectories would be worth it, but it's something to consider.
>
> Oh sure, heck, while we're airing out such things, could I also say it
> annoys me that so many headers cover so many source-files?  I mean, 
> MSVC is
> smart enough to not recompile source files if no "relevant" changes were
> made in the header, but most build systems aren't, so changing a source 
> file
> and an entry in its related header file forces you to rebuild like half 
> the
> project.  I mean, yeah yeah, interfaces are supposed to be stable, etc. 
> but
> I still think the headers could be more "granular" rather than 
> "aggregate".
> I have to confess to creating a couple new headers with more limited 
> scope,
> handling interfaces between subsystems, so that intimate changes to 
> those
> would not cause all the source files that have just casual dealings 
> with the
> subsystems to have to be rebuilt.  This interface-identification should
> probably be done a little more... rigorously, though.
>
> As for removing dead code, maybe there should be a general policy that 
> if
> you come across some, are not the one who replaced the dead code with 
> newer
> code, and verify that you think the newer code completely replaces the 
> old
> code, you're authorized to delete the dead code.  I mean, it will live 
> on in
> the CVS history anyway.  And, it makes sure that changes like this get
> double-checked (by two different people - the author and the reviewer) 
> for
> extra robustness.  Having dead code sitting around does mess up 
> grep-style
> mass searches and the like, so it would be nice to see it get threshed 
> out
> from time to time.
>
> Comments appreciated...
>
> Woody
>
> PS If "thresh" it not the stage of grain-harvesting that separates the 
> germ
> from the chaff, s/thresh/whatever that verb is/.

PPS 'wrt' (as in the subject line) is 'with respect to', in case not all 
mathematics curricula use that abbreviation.