Existe-t-il un moyen d'accélérer la Javadoc (prend 7 minutes) ?

Question

Je suis en train de construire une Javadoc pour un module avec 2.509 classes. Cela prend actuellement 7 minutes, soit 6 fichiers par seconde.

J'ai essayé

mvn -T 1C install

Cependant javadoc n'utilise qu'une seule unité centrale. Existe-t-il un moyen d'en utiliser davantage et/ou de l'accélérer ?

J'utilise Mise à jour Oracle JDK 8 112 . Ma machine de développement a 16 cœurs et 128 Go de mémoire.

En lançant l'enregistreur de vol, je constate qu'il n'y a qu'un seul fil. main

Pour les personnes intéressées, j'ai utilisé les options suivantes :

<plugin>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
        <additionalJOptions>
            <additionalJOption>-J-XX:+UnlockCommercialFeatures</additionalJOption>
            <additionalJOption>-J-XX:+FlightRecorder</additionalJOption>
            <additionalJOption>-J-XX:StartFlightRecording=name=test,filename=/tmp/myrecording-50.jfr,dumponexit=true</additionalJOption>
            <additionalJOption>-J-XX:FlightRecorderOptions=loglevel=debug</additionalJOption>
        </additionalJOptions>
    </configuration>
</plugin>

REMARQUE : une solution de contournement consiste à faire :

-Dmaven.javadoc.skip=true

Answer 1

Si vous avez un projet multi-modules, il construira au mieux le javadoc de chaque module en parallèle (si votre graphe de dépendance entre les modules le permet).

Le processus javadoc lui-même est monotâche, de sorte que vous ne pourrez pas utiliser plusieurs cœurs pour générer le javadoc d'un seul module.

Cependant, étant donné que vous avez beaucoup de classes (et peut-être beaucoup de doclets @link ou similaires ?), peut-être que le processus javadoc pourrait bénéficier d'un tas étendu. Avez-vous examiné l'activité du GC ? Essayez d'ajouter ceci dans votre configuration, voyez si cela vous aide :

<additionalJOption>-J-Xms2g</additionalJOption>
<additionalJOption>-J-Xmx2g</additionalJOption>

Answer 2

@lbndev a raison, au moins avec le Doclet par défaut ( com.sun.tools.doclets.formats.html.HtmlDoclet ) qui est fournie avec la Javadoc. Un coup d'œil sur le code source confirme l'implémentation d'un seul thread :

• Le point de départ est la classe mère AbstractDoclet.startGeneration()
• Il s'agit alors d'un appel à new ClassTree() qui appelle ClassTree.buildTree() qui utilise un for boucle pour itérer la liste des classes, générant des modèles de classes
• L'étape suivante est AbstractDoclet.generateClassFiles() , encore une fois un for boucle sur les paquets
• Il s'agit ensuite de HtmlDoclet.generateClassFiles() qui itère package.allClasses() , toujours dans un for boucle.

(Ces liens renvoient aux sources du JDK 8. Avec le JDK 11, les classes ont été déplacées, mais la base for boucles en HtmlDoclet y AbstractDoclet sont toujours là).

Certains profils basés sur des échantillons ont confirmé que ces méthodes constituaient un goulot d'étranglement :

Ce ne sera pas ce que vous espériez entendre, mais il semble qu'il n'y ait pas d'option dans la Javadoc standard actuelle pour le multithreading, au moins dans un seul module Maven.

generateClassFiles() etc. se prêteraient bien à un peu de multithreading, bien qu'il faille probablement modifier le JDK. Comme mentionné ci-dessous AbstractDoclet.isValidDoclet() bloque même activement la sous-classification des HtmlDoclet . Essayer de réimplémenter certaines de ces boucles en tant que tiers nécessiterait d'intégrer un grand nombre d'autres codes.

Un examen d'autres implémentations de Doclet (par ex. javadown ) n'a trouvé qu'un style d'implémentation similaire autour de l'exploration des paquets et des classes. Il est possible que d'autres personnes sur ce fil de discussion en sachent plus.

Si l'on réfléchit un peu plus largement, il est possible de trouver des solutions autour de DocFileFactory . Elle est clairement identifiée comme une classe interne (elle n'est même pas publique dans le paquet), mais elle fait abstraction de l'écriture des fichiers (HTML). Il semble possible qu'une version alternative de ce programme puisse mettre en mémoire tampon le HTML, ou l'envoyer directement vers un fichier zip, afin d'améliorer les performances IO. Mais il est clair que cela nécessiterait également de comprendre le risque de changement dans les outils du JDK.

Answer 3

Javadoc, et le doclet standard, sont actuellement fondamentalement mono-thread.

Il est prévu d'améliorer cette situation, principalement en générant des pages en parallèle, mais cela implique d'adapter la sécurité de la MT à diverses structures de données partagées.

Answer 4

Vous pouvez demander à Maven d'utiliser plusieurs threads par cœur dans tous les cœurs.

Par exemple.

mvn -T 4C install # will use 4 threads per available CPU core

Vous pouvez modifier 4 ci-dessus à la valeur de votre choix. Vous avez une machine avec beaucoup de ressources. Essayez 8 ou 16 .

Avez-vous également essayé d'utiliser javadoc-no-fork ? Cela permettra de s'assurer que la javadoc n'est pas déclenchée une deuxième fois - https://maven.apache.org/plugins/maven-javadoc-plugin/examples/javadoc-nofork.html

Answer 5

La personnalisation de Maven est un moyen d'accélérer la génération de javadoc.

Une autre approche consisterait à modifier le doclet utilisé pour générer la javadoc. Le plugin javadoc de maven vous permet de changer le doclet utilisé pour générer le javadoc.

https://maven.apache.org/plugins/maven-javadoc-plugin/examples/alternate-doclet.html

J'ai trouvé la doclet commerciale suivante (je ne suis en aucun cas affilié à eux) qui prétend être plus rapide que la javadoc traditionnelle. Il propose une licence gratuite/essai/commerciale. Si vous êtes vraiment désireux d'accélérer votre construction de javadoc, cela vaut peut-être la peine de regarder si le prix en vaut la peine.

http://www.filigris.com/docflex-javadoc

Il existe peut-être des alternatives opensource sur internet...