Re: [Freeciv-Dev] change includes

[Mitch Davis <mjd@xxxxxxxxxx>]

Trent Piepho wrote:
> 
> Currently all the freeciv include files are included with <>, rather than "".
> 
> I purpose to change this.  This way multiple -I lines won't be needed to
> compile the program, and autodependencies can exclude system header files like
> they are supposed to.  Does anyone see anything wrong with this?  This is
> an example of what I would change the headers too.

> Currently:
> #include <stdio.h>
> #include <stdlib.h>
> #include <packets.h>
> #include <climisc.h>
> #include <game.h>
> #include <mapview.h>

> Becomes:
> 
> #include <stdio.h>
> #include <stdlib.h>
> #include "common/packets.h"
> #include "client/climisc.h"
> #include "common/game.h"
> #include "client/mapview.h"

As I mentioned, here's my take:

I'm not in a mad keen rush to go changing this sort of
thing at the moment:  It may be ugly, and lead to long
compile lines, but we know it works effectively 100%
of the time, and I'm not looking to risk breaking anything
this late in the peace!! :-)

You're actually proposing two changes here.

 - To replace #include <> with #include "".
 - To remove the need for many command-line -I clauses,
   by explicitly specifying the directory a header lives in.

The first is a common source of confusion for people.  In a
nutshell, there is only one difference between the two, and
you can verify it with gcc -v, if you're using gcc.

In both cases, the compiler searches a list of directories
for the header.

 - For #include <>, the list is:

   - In order, any directories you've specified using -I
   - In order, the implicit list of directories built into
     the compiler.  /usr/include is one of these.

 - For #include "", the list is:

   - The current directory.
   - In order, any directories you've specified using -I.
   - In order, the implicit list of directories built into
     the compiler.  /usr/include is one of these.

So, the only difference between them is that "" searches the
current directory before the -I and system dirs.  That's
why #include "stdio.h" works, even though by convention it's 
#include <stdio.h>.  (Conversely, doing an #include <stdio.h>
will pick up the system one [or one in a -I dir], even if
there's a stdio.h in the current directory)

So the only reason you'd want to use "" over <> is if you
definitely wanted to pick up include files out of the
current directory.  Any other percieved difference (such
as, ``we always use "" to indicate a header in our project, and
<> to indicate a header outside'' is as a result of misguided
convention, rather than a true understanding of the
difference between them.  (I welcome corrections if I have
this wrong.  Also, I won't go into the -nostdinc and -I-
gcc cpp directives, which only further complicate matters.)

When Freeciv was still run by the Danish authors (principly
Peter Unold, as Claus and Allan had by that time lost
interest), all include files used to be in a separate
include directory.  At that time, I changed all the ""'s
to be <>, because none of the .h files were ever in the
current directory.  This correctly reflected the difference
between "" and <>.

About the time of the transition of Freeciv to Trent and I,
one of Peter's final (and far-sighted) moves was to abolish
the include/ directory, and put include files near their
corresponding .c files.

The downside of this is that now there are many cases where
a header must be included from the current directory:
eg, citydlg.c must include citydlg.h, which is in the same dir.
This is problematic, as it means that Freeciv will not
compile _without_ a -I.

There's a wart I'll get to in a moment, but basically, 
changing <> to "" would be correct when a .h must be
included from the same dir as the .c.  My preferred
arrangement for this would be:

#include <system1.h>
#include <system2.h>

#include <X11/x11a.h>
#include <X11/x11b.h>

#include <Xaw/xaw1.h>
#include <Xaw/xaw2.h>

#include <otherdir1.h>
#include <otherdir2.h>

#include "thisdir1.h"
#include "thisdir2.h"

Putting the includes of the otherdir's before the thisdir's has
one added benefit:  You find out if something in the other dir
depends on something in this dir (which it shouldn't).

I'd be all in favour of changing the thisdir's to "", except
for the wart I mentioned before:  We've seen a patch or two
which allows people to build Freeciv into a separate directory
from the source.  Although the -I. is necessary for building
because of the bug described above, it's in there at the
moment because it is the degenerate form of -I$(srcdir):
$(srcdir) for most people is ".".

I'm not 100% sure here, but I'm guessing that without the <>,
and the explicit -I, this feature will stop working, so this
needs carefully checking.

Again, if you want to change the <> to "" for headers in the
local directory, and the build-elsewhere feature works, and
you can pull all the #include ""'s to be after the
#include <>'s, I'm in favour.

Now, the second issue:  Explicitly specifying the directories
where files are found.

I don't have a rabid opinion either way on this:  Having the
directory name in the file _would_ shorten the compile line,
but I don't see that it's anywhere near the problem all the
-D entry were.  And I think David has made a very good point
when he talks about methods for selecting different files at
compile time:  We may end up using some sort of switchable
-I entry for choosing widget sets.  Encoding the directory
name might limit us.

Anyway, that's enough of my rambling.  Hope this gives y'all
something to think about! :-)

Regards,

Mitch.
--
| mailto:mjd@xxxxxxxxxx       | Not the official view of: |
| mailto:mjd@xxxxxxxxxxxxxxxx | Australian Calculator Opn |
| Certified Linux Evangelist! | Hewlett Packard Australia |