./configure: Choose data file

[fr33domlover]

Hello,

I'm writing a C/C++ library and using the GNU build system a.k.a autotools. I'm
working on the part which generares an API reference manual in HTML format using
Doxygen. By default I pass my own CSS file to doxygen, which comes from the
source repo, but I'd like to make it easy to try and use different CSS files by
adding an option to ./configure which allows to choose a non-default one. Also,
it will be even more useful to allow choosing between my CSS and doxygen's
auto-generated default CSS.

The HTML is distributed in the tarball so by default a tarball user doesn't
need this option unless she plans to regenerate the API reference pages (which
is unlikely, I suppose), but it can be very useful to the maintainer, who will
be able to choose a CSS file coherent with other docs on the same
system/distro/etc.

What would be an appropriate way to offer such an option? Preferrably it should
appear in ./configure --help, but if not there must be some other good place to
let people know it exists.



Thanks in advance!!!

-- fr33

[Eric Blake]

Post by fr33domlover
What would be an appropriate way to offer such an option? Preferrably it should
appear in ./configure --help, but if not there must be some other good place to
let people know it exists.

AC_ARG_WITH() is probably the most-used solution for this, where you let
the user supply a path name as the argument, and where the option will
be documented in ./configure --help.

AC_ARG_WITH([css-files],
[AS_HELP_STRING([--with-css-files], [location of css files
to use with generated html])],
[ ... set your variable to the user's provided string ... ],
[ ... default your variable to your in-tree location ... ])

lets the end user do ./configure --with-css-files=/path/to/alternate

[fr33domlover]

On 2014-08-13

Post by Eric Blake

Post by fr33domlover
What would be an appropriate way to offer such an option? Preferrably it
should appear in ./configure --help, but if not there must be some other
good place to let people know it exists.

AC_ARG_WITH() is probably the most-used solution for this, where you let
the user supply a path name as the argument, and where the option will
be documented in ./configure --help.
AC_ARG_WITH([css-files],
[AS_HELP_STRING([--with-css-files], [location of css files
to use with generated html])],
[ ... set your variable to the user's provided string ... ],
[ ... default your variable to your in-tree location ... ])
lets the end user do ./configure --with-css-files=/path/to/alternate

This sounds good but I wasn't sure because the autoconf manual says that WITH
is for optional packages. I was worried using it for data files would be
confusing to the user. Should I worry, or is WITH a common/expected solution?
I'm making a reusable solution so I want it to be good :-)

-- fr33

[Eric Blake]

Post by fr33domlover

Post by Eric Blake
lets the end user do ./configure --with-css-files=/path/to/alternate

This sounds good but I wasn't sure because the autoconf manual says that WITH
is for optional packages. I was worried using it for data files would be
confusing to the user. Should I worry, or is WITH a common/expected solution?

This solution is a common usage and fits within the terminology - your
"package" is the alternative css files, and the default is to build
without the alternative css files. Don't worry about it.

[fr33domlover]

On 2014-08-13

Post by Eric Blake
This solution is a common usage and fits within the terminology - your
"package" is the alternative css files, and the default is to build
without the alternative css files. Don't worry about it.

Great :-)
Thank you very much!

-- fr33