Doxygen embeds jquery
This document describes how and why Doxygen embeds jquery. It serves as an
explanation of what problems need to be addressed before removing these
embeddings. If you are not interested in the reasons, skip to consequences.
1. The Doxygen source contains jquery library sources in the `jquery/` folder.
2. These are minified at release time by the Doxygen upstream and stored as
`src/*.js`. See `jquery/Makefile`.
3. They are then converted to C header files and stored as
`generated_src/doxygen/*_js.h`. See `src/libdoxygen.t`.
4. At build-time these headers are compiled into the `doxygen` binary and
installed as `usr/bin/doxygen` into the `doxygen` binary package.
5. When running Doxygen the jquery libraries are embedded into the generated
6. Packages using Doxygen as a build-dependency for creating their
documentation therefore also embed these jquery libraries.
While it would be nice to remove the need for any of these embedding, it is
practically difficult to do so.
6. It was considered to introduce a `doxygen-common` package that pulls in the
relevant jquery libraries and provides them at a canonical location for
usage with symbolic links. When doing this the question of how to handle
upgrades of Doxygen arises. [Upstream indicated] that the documentation
generated with one version of Doxygen will not necessarily work with the
jquery libraries from a different version of Doxygen. This leaves two
* Ship all previous versions of jquery libraries in the `doxygen-common`
* Rebuild all reverse build dependencies of Doxygen whenever uploading a
new version of Doxygen.
Both options were deemed infeasible. The first option simply is
unmaintainable. The second option requires architecture independent
binNMUs. Since the archive does not do any architecture independent
auto-building this is not available either. (This was discussed with the
buildd maintainers during DebConf13.)
5. This is simply how Doxygen is designed to operate. The generated
documentation should be usable as is without dependencies on external
4. To facilitate embedding 5 the `doxygen` binary needs some kind of access
to the jquery libraries. Changing this aspect would require significant
modification of the Doxygen source.
3. These files are regenerated during a regular build.
2. The Debian package recreates these artifacts from step 1 by running `make
-C jquery install` before the build.
1. This is an aspect of the upstream source and build system. Each doxygen
libraries. Replacing them with system copies is simply unmaintainable,
because it is not mechanically testable.
One of the major reasons behind removing embedded copies of code is to be able
to do security updates. Arguably there are little options to exploit a
vulnerable jquery library as embedded by Doxygen, because from a user point of
view it is static data. Thus one of the primary motivations to remove embedded
copies does not apply in this case.
[Upstream indicated]: http://doxygen.10944.n7.nabble.com/release-tarballs-td5837.html
It is not considered a problem for Doxygen or packages using Doxygen to embed
jquery. In fact replacing the `jquery.js` file created by Doxygen likely
results in broken documentation. Packages doing that are buggy. Lintian will
have to learn that a `jquery.js` embedded by Doxygen is a normal thing.