Re: Advice on the project structure for a library

[Ralf Corsepius]

On Tue, 2008-06-03 at 15:29 +0200, Jef Driesen wrote:
> Ralf Wildenhues wrote:
> > * Jef Driesen wrote on Tue, Jun 03, 2008 at 12:31:29PM CEST:
>  CFLAGS=-I${includedir}
>  #include 
> 
>  or
> 
>  CFLAGS=-I${includedir}/libfoo
>  #include 
> > [...]
> >>> It's purely a matter of preference.  You're right to segregate the  
> >>> headers, but a project shouldn't mandate one #include/-I style over 
> >>> another.
> >> I don't really want to mandate a specific style to the users of my  
> >> library. I just want to use the first style inside my own library, and  
> >> right now that doesn't work.

> Is there any preference for choosing libfoo or include/libfoo, or is 
> that just personal taste?
The latter.

I for one prefer this layout
libfoo/Makefile.am
libfoo/configure.ac
libfoo/src/
libfoo/include/foo/

Pro:
* Clean separate of private and public headers
* include/foo can have identical layout as "final installation.
[use #include "xxx.h" for private headers and #include  +
AM_CPPFLAGS = -I$(top_srcdir)/include for public headers]
Con:
* Somewhat tricky to set up with autotools.

Another layout, I am occasionally using is:
libfoo/Makefile.am
libfoo/configure.ac
libfoo/foo/

Pro:
* Slightly easier to use than the approach above.
Con:
* Not keeping private and public headers separate.

Ralf

Re: Building things a little differently?

[Ralf Wildenhues]

* John Calcote wrote on Mon, Jun 02, 2008 at 09:57:12PM CEST:
> Ralf Wildenhues wrote:
> > Automake has no builtin rules for moc files.  So you need to take this
> > up with whoever provides those rules.  FWIW, in one package this is what
> > we use:
> 
> I was wondering how difficult it would be to modify Automake such that
> true extensions could be written.

Well, since almost all content of Makefile.am is copied verbatim into
the output file, you can extend using plain make code.  I understand
that's not what you're after.

> For example, Automake has built-in
> support for Libtool's LTLIBRARIES primitive. Wouldn't it be cool to
> support a type of primary extension file, that would allow one to define
> a new type of primary? This file would provide the rules that a new
> primary would support, lists that it would update - like the distro file
> list, etc.
> 
> Just a thought. Would this be particularly difficult?

Doing this would be much more work.  At least I don't see how it could
be done easily.

Cheers,
Ralf

Re: autoconf-2.62: `make install' fails if file system is case insensitive

[Eric Blake]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

[adding bug-automake and bug-make; this is
http://lists.gnu.org/archive/html/bug-autoconf/2008-05/msg0.html]

According to Keith Marshall on 5/9/2008 2:16 PM:
| If autoconf's Makefile is processed by a GNU make-3.81, which has been
| configured to respect a case insensitive file system, (IMO, the correct
| configuration for use on MS-Windows, among other other systems which
| also have such file systems), and the build is configured directly
| within the source directory, then `make install' fails thus:
|
|   $ make install
|   Makefile:678: warning: overriding commands for target `install'
|   Makefile:574: warning: ignoring old commands for target `install'
|   /bin/sh /home/rgbl0264/foobar/foo/autoconf-2.62/build-aux/missing \
|   --run makeinfo --no-headers --no-validate --no-split  -o install \
|   ./doc/install.texi

Looking further at this, what happens with your case-insensitive make when
running 'make dist' on a project built with 'automake --gnu'?  There,
automake adds an automatic dependency on all 'dist*' targets to unadorned
INSTALL.  Does that mean that 'make dist' will attempt to install the
package when run on MSYS?  Will it just be a no-op because the file
INSTALL already exists?  Is this something that automake needs to address,
by outputting $(abs_srcdir)/INSTALL rather than plain INSTALL in the
dependencies of distdir?

|
| This problem was recently reported by a user on the MinGW users ML:
| http://thread.gmane.org/gmane.comp.gnu.mingw.user/26315
|
| It is not apparent when performing a VPATH build, but is reproducible
| when building in the source directory, both for autoconf-2.62, and for
| earlier versions, (I've also confirmed this for autoconf-2.61).

Because in a VPATH build, $(srcdir)/INSTALL is different than ./INSTALL,
and it looks like case-insensitive GNU make is treating 'make install' and
'make ./INSTALL' as synonyms.  Maybe this is also something that should be
addressed in GNU make, as case-insensitivity makes following GNU Coding
Standards rather difficult?  GNU Coding Standards require the existence of
both 'make install' and './INSTALL'.

|
| This issue may be resolved by replacing each of the three references to
| `$(srcdir)/INSTALL', in the Makefile, by `$(abs_srcdir)/INSTALL'.  I've
| confirmed this, by making the appropriate changes in Makefile.in, and
| then successfully repeating the `./configure && make && make install'
| sequence under MSYS-1.0.11, (with case-insensitive GNU make-3.81), in
| the autoconf-2.62 source directory, on MS-Win2K.  The attached patch,
| against released autoconf-2.62's Makefile.am, will introduce the same
| change, on next Makefile.in regeneration.

That worked for 'make install', but broke 'make dist'; I'm trying to
figure out whether adding:

INSTALL: $(abs_srcdir)/INSTALL

to autoconf's Makefile.am will be making the problem any worse (at least
it fixes the 'make dist' regression when using the normal case-sensitive
GNU make).  Maybe the short answer is that on MSYS (or anywhere else with
case-insensitive GNU make), you should not expect 'make dist*' to work.

- --
Don't work too hard, make some time for fun as well!

Eric Blake [EMAIL PROTECTED]
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkhFlgIACgkQ84KuGfSFAYB1ygCfUvdwoLNeVI3ra4TMb0A1d9m4
YFwAn0m/eukAKMi7LuxKb7wKhidq6yzq
=C2vT
-END PGP SIGNATURE-

Re: -local vs. -hook?

[Karl Berry]

> +You may be tempted to use @code{install-data-local} to install a file
> +to some hard-coded location, but you should avoid this.
> +(@pxref{Hard-Coded Install Paths})

Shouldn't the period be moved from after "this" to after the closing
parenthesis?

Yes.

> +With the @code{-local} targets, there is no particular guarantee of
> +execution order; typically, they are run early, but with parallel
> +make, there is no way to be sure of that.

There isn't even consistency among the various -local targets in their
ordering wrt. other targets.  In fact, I wouldn't even know how many of
them are run at what time, so I'm a bit wary of the "typically"
statement.

By all means, delete "typically" if you prefer.  I was just copying
(with rewording) from your mail :).

Thanks,
k

Re: extending automake

[Ralf Wildenhues]

Hello Bob,

* Bob Rossi wrote on Tue, Jun 03, 2008 at 05:58:59PM CEST:
> Another example I just ran across on the mingw.org site,
>windres -o resfile.o resfile.rc
>gcc -o hello hello.o resfile.o -mwindows
> Often people want to put resources into there program. They would
> greatly benefit from this feature, considering they could teach automake
> how to run these commands.

Wait, the above example is about extending automake, but not about rules
which produce multiple output files, right?

For the above, I'd just use (assuming SUFFIXES has already been set)

SUFFIXES += .rc
WINDRES = windres
.rc.$(OBJEXT):
$(WINDRES) $(WINDRESFLAGS) -o $@ $<

bin_PROGRAMS = hello
hello_SOURCES = hello.c
# probably the following needs to go in a conditional
hello_LDADD = resfile.$(OBJEXT)


Hope that helps.

Cheers,
Ralf

Re: extending automake

[Bob Rossi]

On Thu, May 01, 2008 at 03:48:25PM -0400, Bob Rossi wrote:
> On Wed, Apr 30, 2008 at 03:21:18PM +0200, Ralf Wildenhues wrote:
> > * Bob Rossi wrote on Wed, Apr 30, 2008 at 02:59:11PM CEST:
> > > You busy or thing the idea is no good?
> > 
> > Busy.  If you want to help, there are still unaddressed questions from 
> > 
> > 
> > (even if the above notation is not adopted, its semantics are still
> > close to what automake should be able to provide; so you could try
> > and report whether those semantics fit your particular problem
> > instance).
> 
> Hi Ralf,
> 
> MULTITARGETS = elc-stamp
> elc_stamp_TARGETS = $(ELCFILES)
> elc_stamp_SOURCES = $(ELFILES)
> elc_stamp_COMMAND = \
> for f in : $(elc_stamp_SOURCES); do \
>   test "$$f" != : || continue; \
>   touch "$${f}c"; \
> done
> 
> Something like this is exactly what would help me. For instance, I'm
> thinking I could do,
> 
>   MULTITARGETS = gen-foo
>   gen_foo_TARGETS = $(srcdir)/foo.xml $(abs_top_srcdir)/gen.py
>   gen_foo_SOURCES = foo.h foo.c
>   gen_foo_COMMAND = python $(abs_top_srcdir)/gen.py $(srcdir)/foo.xml
> 
> is that correct? Also, how would I tell automake that this should be
> done at BUILT_SOURCES time?
> 
> This would also work for flex/bison in the case that Mike Mueller asked
> about.

Another example I just ran across on the mingw.org site,
   windres -o resfile.o resfile.rc
   gcc -o hello hello.o resfile.o -mwindows
Often people want to put resources into there program. They would
greatly benefit from this feature, considering they could teach automake
how to run these commands.

Have you had any time to think about this?

Thanks,
Bob Rossi

Re: Advice on the project structure for a library

[Warren Young]

Jef Driesen wrote:
If your headers use the libfoo/header.h style, your users must, too. 
That's not consistent with your wish above.


Why is that necessary? Isn't the toplevel directory (where the 
libfoo/header.h is located) also included, even if the user is using a 
 include style? Or is that only true if the headers are 
installed in the standard /usr/include location?


There's nothing preventing one of your users from installing 'libfoo' 
other than under one of the standard system include directories.  If 
someone did that, #include "header.h" will still work, but #include 
 will only work if you give a -I flag to the compiler, 
giving the parent directory holding 'libfoo'.


This is a usability matter, not a works/doesn't work matter.

I also checked a number of libraries 
on my system (cairo, gtk, just to name a few), and none of them has 
"header.h" includes. They all have  includes, with a few 
exceptions that have  includes (openssl for instance). 
Is there another reason for that?


As Bob said, the C and C++ standards are vague on this matter.  You 
should try both and see how the compilers you use actually behave.


I maintain a free library myself (http://tangentsoft.net/mysql++/), and 
what I'm telling you comes from my experience with these very issues. 
We dealt with all this stuff years ago in MySQL++.  We found that using 
double quotes for "peer" header includes works reliably across all 
compilers we target, where we had problems with angle bracket includes. 
 MySQL++ targets several Windows compilers, which may be relevant here. 
 If your library will live a more sheltered existence, you might get 
away with angle brackets.

Re: Advice on the project structure for a library

[Bob Friesenhahn]

On Tue, 3 Jun 2008, Warren Young wrote:


Suppose that in one of my public headers, I include one of the other header 
files, with  style. 


If your headers use the libfoo/header.h style, your users must, too. That's 
not consistent with your wish above.


To allow your users choice in the matter, your public headers should use this 
style when pulling in other headers from the same project:


#include "my-other-header.h"

The use of "" instead of <> tells the compiler to look in the current 
directory before going through the list of other possible directories. This 
is exactly what you want when you don't know where the user has installed the 
headers.  A side benefit is that it protects you if there is a 
my-other-header.h on the system in one of the other directories in the 
include path; the compiler will always use the right one.


I think that "suggests" is a better operative word than "tells".  Last 
I checked, the C standard left quite a lot up to the implementation.


When using a VPATH build, the value of double quote syntax may be 
significantly diminished to the extent it does not help at all.  Any 
project using Automake should reliably support a VPATH build as long 
as make supports it (passing 'make distcheck').  Sometimes it is 
necessary to manually inspect generated header dependency files to 
make absolutely sure that the correct headers are used.


With today's messy include directories, creating a directory for the 
project header is a good idea, and so there is no harm to using 
 style.


Bob
==
Bob Friesenhahn
[EMAIL PROTECTED], http://www.simplesystems.org/users/bfriesen/
GraphicsMagick Maintainer,http://www.GraphicsMagick.org/

Re: Advice on the project structure for a library

[Jef Driesen]

Warren Young wrote:

Jef Driesen wrote:
I don't really want to mandate a specific style to the users of my 
library. 


[snip]

Suppose that in one of my public headers, I include one of the other 
header files, with  style. 


If your headers use the libfoo/header.h style, your users must, too. 
That's not consistent with your wish above.


Why is that necessary? Isn't the toplevel directory (where the 
libfoo/header.h is located) also included, even if the user is using a 
 include style? Or is that only true if the headers are 
installed in the standard /usr/include location?


To allow your users choice in the matter, your public headers should use 
this style when pulling in other headers from the same project:


#include "my-other-header.h"

The use of "" instead of <> tells the compiler to look in the current 
directory before going through the list of other possible directories. 
This is exactly what you want when you don't know where the user has 
installed the headers.  A side benefit is that it protects you if there 
is a my-other-header.h on the system in one of the other directories in 
the include path; the compiler will always use the right one.


That sounds reasonable to me. But I also checked a number of libraries 
on my system (cairo, gtk, just to name a few), and none of them has 
"header.h" includes. They all have  includes, with a few 
exceptions that have  includes (openssl for instance). 
Is there another reason for that?


The code style you use in your examples is another matter entirely.  One 
way to fix it would be to make a symlink in the examples directory:


$ cd examples
$ ln -s ../src libfoo

If you're using a VCS that understands symlinks (e.g. svn, but not cvs) 
and always target POSIX systems, you can keep the symlink in the 
repository, and add it to EXTRA_DIST so it gets put in the tarball.


If you're targeting POSIX only but can't store the symlink in the 
repository, you can create it in examples/Makefile.am:


all-local:
ln -s ../src libfoo

(It might have to be moved up to the top-level Makefile.am to have the 
operations go in the right order.)


If you have to deploy on non-POSIX systems, then you have no choice but 
to reorganize your source tree, as Ralf suggested.


I want to support Windows, so I can't use symlinks.

Re: Advice on the project structure for a library

[Jef Driesen]

Ralf Wildenhues wrote:

* Jef Driesen wrote on Tue, Jun 03, 2008 at 12:31:29PM CEST:

CFLAGS=-I${includedir}
#include 

or

CFLAGS=-I${includedir}/libfoo
#include 

[...]
It's purely a matter of preference.  You're right to segregate the  
headers, but a project shouldn't mandate one #include/-I style over 
another.
I don't really want to mandate a specific style to the users of my  
library. I just want to use the first style inside my own library, and  
right now that doesn't work.


Good thinking.  The first style helps avoid name clashes with generic
header file names.


That's exactly the reason why I wanted to use that style.

Suppose that in one of my public headers, I include one of the other  
header files, with  style. Now when I compile the  
library in my src tree, it fails because there is no such header present  
in my src tree or system wide (not installed yet). The same for the  
examples.


Can you reorganize your source tree to look more like the installed
tree?  IOW, move headers in a subdirectory libfoo or include/libfoo.
The biggest reason against doing so, namely that CVS doesn't track
renames, isn't very relevant any more nowadays.


I can reorganize my source tree anyway I want. I'm using subversion, so 
renaming is no problem.


Is there any preference for choosing libfoo or include/libfoo, or is 
that just personal taste?

Re: Advice on the project structure for a library

[Warren Young]

Jef Driesen wrote:
I don't really want to mandate a specific style to the users of my 
library. 


[snip]

Suppose that in one of my public headers, I include one of the other 
header files, with  style. 


If your headers use the libfoo/header.h style, your users must, too. 
That's not consistent with your wish above.


To allow your users choice in the matter, your public headers should use 
this style when pulling in other headers from the same project:


#include "my-other-header.h"

The use of "" instead of <> tells the compiler to look in the current 
directory before going through the list of other possible directories. 
This is exactly what you want when you don't know where the user has 
installed the headers.  A side benefit is that it protects you if there 
is a my-other-header.h on the system in one of the other directories in 
the include path; the compiler will always use the right one.


The code style you use in your examples is another matter entirely.  One 
way to fix it would be to make a symlink in the examples directory:


$ cd examples
$ ln -s ../src libfoo

If you're using a VCS that understands symlinks (e.g. svn, but not cvs) 
and always target POSIX systems, you can keep the symlink in the 
repository, and add it to EXTRA_DIST so it gets put in the tarball.


If you're targeting POSIX only but can't store the symlink in the 
repository, you can create it in examples/Makefile.am:


all-local:
ln -s ../src libfoo

(It might have to be moved up to the top-level Makefile.am to have the 
operations go in the right order.)


If you have to deploy on non-POSIX systems, then you have no choice but 
to reorganize your source tree, as Ralf suggested.

Re: Advice on the project structure for a library

[Ralf Wildenhues]

* Jef Driesen wrote on Tue, Jun 03, 2008 at 12:31:29PM CEST:
>>> CFLAGS=-I${includedir}
>>> #include 
>>>
>>> or
>>>
>>> CFLAGS=-I${includedir}/libfoo
>>> #include 
[...]
>> It's purely a matter of preference.  You're right to segregate the  
>> headers, but a project shouldn't mandate one #include/-I style over 
>> another.
>
> I don't really want to mandate a specific style to the users of my  
> library. I just want to use the first style inside my own library, and  
> right now that doesn't work.

Good thinking.  The first style helps avoid name clashes with generic
header file names.

> Suppose that in one of my public headers, I include one of the other  
> header files, with  style. Now when I compile the  
> library in my src tree, it fails because there is no such header present  
> in my src tree or system wide (not installed yet). The same for the  
> examples.

Can you reorganize your source tree to look more like the installed
tree?  IOW, move headers in a subdirectory libfoo or include/libfoo.
The biggest reason against doing so, namely that CVS doesn't track
renames, isn't very relevant any more nowadays.

Cheers,
Ralf

Re: Advice on the project structure for a library

[Jef Driesen]

Warren Young wrote:

Jef Driesen wrote:
I noticed it is common practice to install the public headers to 
$includedir/libfoo


I don't think I've ever seen a 'lib' prefix on a header file directory. 
  $includedir/foo is far more common.


It's also common for 'foo' to be a diminutive, lowercased version of the 
project's full name.  For example, Gnome's GTK+ headers are typically 
installed in gtk/*.h.  It would go against convention if they were 
instead installed in GTK+/*.h.


Such directories do exist on my system (e.g. libpng, libexif, libxml2, 
etc). My project name is already lowercase, so that is not an issue.



CFLAGS=-I${includedir}
#include 

or

CFLAGS=-I${includedir}/libfoo
#include 

I think the first one is preferable (but I might be wrong), 


It's purely a matter of preference.  You're right to segregate the 
headers, but a project shouldn't mandate one #include/-I style over another.


I don't really want to mandate a specific style to the users of my 
library. I just want to use the first style inside my own library, and 
right now that doesn't work. So I want to know how to fix that :-)


if I use the 
 style include in my project, it fails to build 
anything, because the header files are not installed yet and thus can't 
be found.


This is why you don't want to bake such policy into the design of your 
library.  Your examples can use #include , with -I../src. 
Your users can use  with no -I if foo is under a system 
include directory, or  with an explicit -I otherwise.


I think I made it not very clear what is going wrong, so I'll try again.

Suppose that in one of my public headers, I include one of the other 
header files, with  style. Now when I compile the 
library in my src tree, it fails because there is no such header present 
in my src tree or system wide (not installed yet). The same for the 
examples.

Re: Advice on the project structure for a library

[Warren Young]

Jef Driesen wrote:


I noticed it is common practice to install the public headers to 
$includedir/libfoo


I don't think I've ever seen a 'lib' prefix on a header file directory. 
 $includedir/foo is far more common.


It's also common for 'foo' to be a diminutive, lowercased version of the 
project's full name.  For example, Gnome's GTK+ headers are typically 
installed in gtk/*.h.  It would go against convention if they were 
instead installed in GTK+/*.h.



CFLAGS=-I${includedir}
#include 

or

CFLAGS=-I${includedir}/libfoo
#include 

I think the first one is preferable (but I might be wrong), 


It's purely a matter of preference.  You're right to segregate the 
headers, but a project shouldn't mandate one #include/-I style over another.


if I use the 
 style include in my project, it fails to build 
anything, because the header files are not installed yet and thus can't 
be found.


This is why you don't want to bake such policy into the design of your 
library.  Your examples can use #include , with -I../src. 
Your users can use  with no -I if foo is under a system 
include directory, or  with an explicit -I otherwise.

Advice on the project structure for a library

[Jef Driesen]

I'm creating my first autoconf/automake project and need some advice on
the standard way to structure my project source code (if there is such a
thing). My project consist of a (libtool) library and a few example
applications that are using the library.

Right now my directory structure is as follows:

\  configure.ac, toplevel Makefile.am
\src   Makefile.am, *.h and *.c files for the library
\examples  Makefile.am, *.h and *.c files for the examples

I noticed it is common practice to install the public headers to 
$includedir/libfoo (rather than straight into $includedir), especially 
when the library has multiple public header files. So that's what I'm doing.


For applications depending on the library, I noticed there are two 
approaches in use:


CFLAGS=-I${includedir}
#include 

or

CFLAGS=-I${includedir}/libfoo
#include 

I think the first one is preferable (but I might be wrong), because it 
makes it very clear from which library the header file is included. And 
there is also no possibility of conflicts with a header file of the same 
name from another package.


But how do structure my project to make this work? Everything I tried 
fails to build either the library or the examples, because of problems 
with finding the header files. For instance, if I use the 
 style include in my project, it fails to build 
anything, because the header files are not installed yet and thus can't 
be found.