Doxygen jest wolny

Question

Doxygen trwa około 12 godzin, aby uruchomić na naszej bazie kodu. Dzieje się tak głównie dlatego, że jest dużo kodu do przetworzenia (~ 1,5 M linii). Jednak bardzo szybko zbliża się moment, w którym nie możemy dokonywać nocnych aktualizacji dokumentacji, ponieważ trwa to zbyt długo. Musieliśmy już zmniejszyć głębokość wykresu, aby uzyskać 12 godzin.

Próbowałem standardowych podejść, ale naprawdę potrzebuję wysokiej jakości wyników, a to obejmuje wykresy i SEARCH_INCLUDES. Mam dość dobrą maszynę do uruchamiania Doxygen, ale Doxygen nie wykorzystuje wielu swoich rdzeni. (Łączy pojedynczy procesor na serwerze kompilacji, ale stanowi tylko 4% dostępnego systemu.) Posiadanie wielowątkowej konstrukcji Dot jest wygodne, ale to tylko połowa czasu budowy.

Czy są jakieś techniki, których można użyć do uruchomienia doxygen w wielu procesach i ręcznie odrzucić zadanie? Widziałem kilka rozmów na temat tworzenia plików znaczników, ale nie rozumiem ich wystarczająco dużo, aby wiedzieć, czy robią to, co chcę. Co szukam jest coś takiego:

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 

Oczywiście, ja tylko czyni rzeczy, ale to jest pomysł, co szukam. Ponadto użyłbym więcej niż 4 procesów.

Answer 1

pliki Tag są zazwyczaj do zrobienia jeśli

1. masz wiele plików źródłowych logicznie spójnych (nazwijmy je częściami) oraz
2. wiesz zależności między składnikami, na przykład składnik A wykorzystuje komponent B i C, a komponent B używa tylko C, i
3. Jest ok (lub nawet preferowany), że pliki indeksowe (na przykład lista plików/klas/funkcji) są ograniczone do pojedynczego komponentu.
4. Interesuje Cię wynik HTML.

Plik znaczników to w zasadzie uporządkowana lista symboli z linkami do lokalizacji w dokumentacji. Pliki znaczników umożliwiają doxygen tworzenie linków z dokumentacji jednego komponentu do drugiego.

Jest to proces 2 krok:

1. pierwszym uruchomieniu doxygen na każdego komponentu, aby wygenerować plik znacznika dla tego komponentu. Możesz to zrobić, wyłączając wszystkie dane wyjściowe i użyj GENERATE_TAGFILE. Więc dla komponentu A, Doxyfile.tagonly miałoby następujące ustawienia:

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

   Zauważysz, że ten sposób działa doxygen jest bardzo szybko.

2. Drugim krokiem jest wygenerowanie aktualnej dokumentacji. W przypadku komponentu A potrzebny jest plik Doxy, który zawiera pliki znaczników komponentów B i C, ponieważ ustaliliśmy, że A zależy od tych składników.

   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 
   

Stosując to podejście udało mi się wygenerować dokumentację dla 20m + linii kodu rozmieszczonych na ponad 1500 elementów w ciągu 3 godzin w standardowym komputerze PC (Core i5 8GB RAM i Linux 64bit) w tym przeglądanie źródła, pełne wykresy połączeń i schematy UML w stylu wszystkich struktur danych. Zauważ, że pierwszy krok trwał tylko 10 minut.

W tym celu stworzyłem skrypt do generowania plików Doxy dla każdego komponentu na podstawie listy komponentów i ich bezpośrednich zależności. W pierwszym kroku równolegle wykonuję 8 instancji doxygena (przy użyciu http://www.gnu.org/s/parallel/). W drugim kroku równolegle uruchamiam 4 instancje doxygena.

Aby uzyskać więcej informacji o plikach znaczników, zobacz artykuł http://www.doxygen.org/external.html.