Doxygen è lento

Question

Doxygen impiega circa 12 ore per funzionare sulla nostra base di codice. Questo è principalmente dovuto al fatto che c'è un sacco di codice da elaborare (linee ~ 1.5M). Tuttavia, si sta rapidamente avvicinando al punto in cui non possiamo fare gli aggiornamenti della documentazione notturna perché impiegano troppo tempo. Abbiamo già dovuto ridurre la profondità del grafico per ridurlo a 12 ore.

Ho provato gli approcci standard, ma ho davvero bisogno di un output di alta qualità, e questo include grafici e SEARCH_INCLUDES. Ho una macchina abbastanza buona per avviare Doxygen, ma Doxygen non sfrutta i suoi numerosi core. (Mette una singola CPU sul server di build, ma è solo il 4% del sistema disponibile.) Avere una build Dot multithread è comoda, anche se è solo la metà del tempo di costruzione.

Esistono tecniche che è possibile utilizzare per eseguire doxygen tramite più processi e dividere manualmente l'attività? Ho visto alcuni discorsi sulla creazione di file di tag, ma non li capisco abbastanza per sapere se farebbero ciò che voglio. Quello che sto cercando è qualcosa di simile:

doxygen Doxyfile-folder1 
doxygen Doxyfile-folder2 
doxygen Doxyfile-folder3 
doxygen Doxyfile-folder4 
doxygen-join output/folder1/html output/folder2/html output/folder3/html output/folder4/html 

Naturalmente, sto solo facendo roba, ma questa è un'idea di quello che sto cercando. Inoltre, userei molto più di 4 processi.

Answer 1

file tag sono in genere la strada da percorrere se

1. si dispone di un certo numero di file di origine logicamente coerenti (chiamiamoli componenti) e
2. si conoscono le dipendenze tra i componenti, per esempio il componente A utilizza i componenti B e C e il componente B utilizza solo C e
3. È ok (o addirittura preferito) che i file di indice (ad esempio l'elenco di file/classi/funzioni) siano limitati a un singolo componente.
4. sei interessato all'output HTML.

Un file di tag è fondamentalmente solo una lista strutturata di simboli con collegamenti alla posizione nella documentazione. I file di tag consentono a doxygen di creare collegamenti dalla documentazione di un componente a quella di un altro.

Si tratta di un processo in 2 fasi:

1. In primo luogo si esegue doxygen su ogni componente per generare il file tag per tale componente. Puoi farlo disabilitando tutto l'output e usa GENERATE_TAGFILE. Così, per il componente A, un Doxyfile.tagonly avrebbe le seguenti impostazioni:

   GENERATE_HTML   = NO 
   GENERATE_LATEX  = NO 
   GENERATE_RTF   = NO 
   GENERATE_MAN   = NO 
   GENERATE_TAGFILE  = compA.tag 
   

   Si noterà che l'esecuzione doxygen in questo modo è molto veloce.

2. Il secondo passaggio consiste nella generazione della documentazione effettiva. Per il componente A è necessario un Doxyfile che includa i file di tag dei componenti B e C poiché abbiamo determinato che A dipende da questi componenti.

   GENERATE_HTML   = YES 
   GENERATE_LATEX  = NO 
   GENERATE_RTF   = NO 
   GENERATE_MAN   = NO 
   TAGFILES    = path/to/compB/compB.tag=path/to/compB/htmldocs \ 
            path/to/compC/compC.tag=path/to/compC/htmldocs 
   

Usando questo approccio sono stato in grado di generare documentazione per 20M + linee di codice distribuiti su 1500+ componenti in meno di 3 ore su un PC desktop standard (Core i5 con 8 GB di RAM e 64 bit di Linux), tra cui la navigazione di origine, i grafici delle chiamate complete e i diagrammi in stile UML di tutte le strutture di dati. Si noti che il primo passaggio ha richiesto solo 10 minuti.

Per realizzare ciò, ho creato uno script per generare i Doxyfile per ciascun componente in base all'elenco di componenti e alle loro dipendenze dirette. Nel primo passaggio eseguo 8 istanze di doxygen in parallelo (utilizzando http://www.gnu.org/s/parallel/). Nella seconda fase eseguo 4 istanze di doxygen in parallelo.

Vedere http://www.doxygen.org/external.html per ulteriori informazioni sui file di tag.