mirror of https://gitee.com/openkylin/doxygen.git
83 lines
3.6 KiB
Plaintext
83 lines
3.6 KiB
Plaintext
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.
|
|
|
|
Where?
|
|
======
|
|
|
|
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
|
|
documentation.
|
|
6. Packages using Doxygen as a build-dependency for creating their
|
|
documentation therefore also embed these jquery libraries.
|
|
|
|
Why?
|
|
====
|
|
|
|
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
|
|
options:
|
|
|
|
* Ship all previous versions of jquery libraries in the `doxygen-common`
|
|
package.
|
|
* 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
|
|
files.
|
|
|
|
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
|
|
release ships a tightly coupled conglomerate of various javascript
|
|
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
|
|
|
|
Consequences
|
|
============
|
|
|
|
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.
|
|
|
|
Helmut Grohne
|