Date: Tue, 10 Mar 2015 16:01:57 -0700 (PDT) From: Don Lewis <truckman@FreeBSD.org> To: swills@FreeBSD.org Cc: ports@FreeBSD.org Subject: Re: proper DOXYGEN option default value Message-ID: <201503102302.t2AN1vAM086479@gw.catspoiler.org> In-Reply-To: <20150310024736.GB30716@mouf.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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 >> are: >> Pros: >> * Users who need the documentation can use the binary packages if >> they desire >> * This option gets regular exercise on the build cluster >> Cons: >> * 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 >> globally >> >> The pros and cons of removing DOXYGEN from OPTIONS_DEFAULT: >> Pros: >> * 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 >> Cons: >> * Anyone who does need the documentation has to build from the >> port and pay the cost of building and installing doxygen and its >> dependencies. >> * 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: bin/protoc-c include/google/protobuf-c/protobuf-c.h include/protobuf-c/protobuf-c.h lib/libprotobuf-c.a lib/libprotobuf-c.so lib/libprotobuf-c.so.1 lib/libprotobuf-c.so.1.0.0 libdata/pkgconfig/libprotobuf-c.pc 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 breakage.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201503102302.t2AN1vAM086479>