proper DOXYGEN option default value
truckman at FreeBSD.org
Tue Mar 10 23:02:08 UTC 2015
On 10 Mar, Steve Wills wrote:
> On Wed, Mar 04, 2015 at 02:41:48PM -0800, Don Lewis wrote:
>> I maintain a number of ports that use doxygen to generate their
>> documentation. They all list DOXYGEN in OPTIONS_DEFAULT so that
>> the packages will include documentation.
>> I recently received a PR for one of those ports that mentioned that most
>> users don't require the documentation and pointed out that anyone
>> building the port will find it is very painful because of the amount of
>> time it takes to build doxygen and all of its dependencies (primarily
>> all the TeX stuff).
>> It's been my experience that there is enough churn in the dependencies
>> that the whole mess needs to get rebuilt fairly frequently.
>> As I see it, the pros and cons of listing DOXYGEN in OPTIONS_DEFAULT
>> * Users who need the documentation can use the binary packages if
>> they desire
>> * This option gets regular exercise on the build cluster
>> * A bit of extra load on the ports build cluster to install
>> doxygen and its dependencies as a BUILD_DEPENDS for each
>> supported OS version and architecture
>> * The packages are a bit larger
>> * A bit more space is consumed on the user's machine because
>> documentation is installed, even if they don't need it
>> * Users building from ports have to build and install doxygen
>> and it's dependencies unless they take measures to avoid it,
>> either by disabling the option for each port or adding
>> OPTIONS_UNSET=DOXYGEN to their /etc/make.conf to do this
>> The pros and cons of removing DOXYGEN from OPTIONS_DEFAULT:
>> * Less load on the ports build cluster
>> * Smaller packages
>> * Less space consumed on most user machines
>> * Users building from ports who do not need the documentation don't
>> pay the doxygen penalty without taking any special measures
>> * Anyone who does need the documentation has to build from the
>> port and pay the cost of building and installing doxygen and its
>> * The DOXYGEN option would not get regular testing and could be
>> subject to bit rot.
>> Ideally, the documentation could be built and packaged separately. It
>> could even be NO_ARCH. Unfortunately, at this time this would require
>> adding a bunch of new ports just for the documentation.
>> Since these ports only generate HTML documentation, it might be helpful
>> to have a doxygen-lite port that has GRAPHVIZ and LATEX disabled, and
>> use that as a BUILD_DEPENDS. That introduces the problem of conflicts
>> between doxygen and doxygen-lite if someone who builds from ports needs
>> the full featured doxygen for other purposes.
>> Since we have neither of the above, should I leave my ports as-is, or
>> should I disable DOXYGEN by default?
> Personally I would tend to lean towards leaving DOXYGEN off by default,
> especially if there is other accompanying documentation. This is the case for
> lang/ruby* for example.
There's no other documentation in this case. Excluding the DOXYGEN
stuff, this is the entire pkg-plist:
That does sound like a good general guideline, though.
> But beward that this may mean it is more likely that the DOXYGEN parts of the
> plist may become outdated when the doxygen port is updated. So keep testing
> that option.
I've run into that problem when listing the DOXYGEN output explicitly in
pkg-plist. I've since switched to PORTDOCS=* to avoid this source of
More information about the freebsd-ports