I'm setting up a documentation about some sort of Library which consists of a C/C++ part and a VHDL part, plus some instructive doxygen-only pages. They have to be put into one self-contained group. Everything works so far, nice and fluffy...
But what if I want to optimize the output in the vhdl-subdirectory by using OPTIMIZE_OUTPUT_VHDL = YES and optimize the output of the c-subdirectory by using OPTIMIZE_OUTPUT_C = YES at the same time?
As far as I understand, using doxygen-tags is not optimal in my case, since it introduces new doxyfile.conf-files in each subdirectory, with independent runs of doxygen in each subdirectory. So, doing this I can't put both parts (c+vhdl) in different subgroups of the same group anymore, and links between the two parts are not possible. Also, the whole module should be "selfcontained", to be includable into bigger documentations, without the special build-structure involved in this solution...
What would you do?
I had the same problem - eventually what we did is:
Create a different directory for C code and VHDL code (+ respective doxygen comment files - as we didn't want to spam the code with doxygen tags everywhere).
Run Doxygen for each of these directories (each with it's own oprimization tag - OPTIMIZE_OUTPUT_VHDL or OPTIMIZE_OUTPUT_C )
Combine (manually!!!- though you can create a script for it) the output of these two directories such that the main page would reference the two directories.
Eventually I decided to shorten the time it takes to generate the documentation, and I just ignore the optimization tags...
Related
I've been reading everywhere about the need to organize your R projects and also to use Rmarkdown.
I see an incoherence I can't solve.
Suppose I set for the following standard organization:
Project
data
raw-data
code
docs
out
reports
and also home of setwd().
Now I want to use Rmarkdown with my main project file called My_project.Rmd
I create it at the root project level, then I get at every knit rendition 2 directories created My_project_cache and My_project_files on to of every .hml file rendered that conflicts with the above structure.
This is very impractical.
I tried setting the options of output to avoid this, per this tip, but it fails on the cache directory, and I did not succeeded in setting Knit options to bypass it. And no-one seems to be bothered by this question making the solution look like a dead-end.
The other solution is to put My_project.Rmd directly in reports/ but it feels a little awkward and on top of that it breaks the above project structure by imposing ../ paths everywhere.
The third solution is to work with Rmd format, only at the end of a project, but this seems a little defeating the purpose of documenting everything neatly in the first place.
There may be a 4th solution using R Notebook feature, but it works until you decide to try to finalize your "final" document , which of course is never really final.
What am I missing here ?
For reference, I'm using RStudio on a Mac.
I am currently documenting a F95/2003 software project with the help of doxygen. On the one hand I grouped corresponding pages with the help of #defgroup, #addtogroup, #ingroup.... which end up under the point Modules in the table of contents and the top menu. Then the project also contains Fortran Modules, properly documented, and they appear also as a separate Modules point in the table of contents, which makes them hard to distinguish. How can I rename one of them? Like naming the Module pages generated from the Fortran modules' documentation as Fortran Modules or the best option would be to get completely rid of the separate Modules pages for the Fortran modules, since they also belong to a doxygen group and can be found there asl well?
In principle the "Fortran modules" are listed as namespaces, but by means of the OPTIMIZE_FOR_FORTRAN = YES the name is changed into "Modules". To get the correct naming is of course a difficult problem.
Doxygen has also the possibility to change, in respect to names and showing / hiding) some layout elements, see the doxygen manual paragraph: "Changing the layout of pages" (http://doxygen.nl/manual/customize.html#layout).
when creating a layout file say:
doxygen -l mylayout.xml
and changing here the line (approximately line 8):
<tab type="namespaces" visible="yes" title="">
into
<tab type="namespaces" visible="yes" title="Fortran Modules">
and setting in the doxygen configuration file (Doxyfile):
LAYOUT_FILE = mylayout.xml
I think you get the effect you want to have.
The following I didn't try (so I don't know what the effect might be in your case, and I have big doubts but I mentioned it here for completeness as it came into my mind), but doxygen has also the \namespace command maybe you can use this in this case in stead of the grouping commands.
I've inherited a large C++ project which I need to port to Linux. There are over 200,000 lines of source in this project spread across more than 300 files. It would be tremendously helpful to have a visual dependency/include tree to refer to for this project so that I can get a general feel for the application's internal structure. This would also help me to locate the "fault lines" between the core modules and Windows header files so that I can stub them out later.
The class viewer in Visual Studio simply isn't cutting it. I was reading around, and learned that Doxygen is a commonly used tool for listing dependencies. I'm much more of a visual person, and found that this wasn't so helpful. Fortunately, I learned about the Graphviz plugin, using something called "Dot" that has enabled me to generate dependency trees for parts. Unfortunately, hundreds of smaller dependency trees are generated for specific files, rather than having one large one as I'd hoped for. Here are a couple of examples:
As you can see (I hope), Doxygen/GraphViz seem to give up when the graph gets too large and gray out the child nodes. I then have to go to the graph for that specific node if I want to see what's further down the tree. Not only does this limit the visual helpfulness of the graph, but if the child node depends on any of the nodes from the original graph, these nodes will be shown again. This is leading to lots of duplicate connections that make it very hard to conceptually isolate the graph from any given file. As a result, I feel like I'm "zoomed in" and still can't see the whole picture.
I've tried playing around with the DOT_GRAPH_MAX_NODES setting in the Expert view in Doxygen, but this doesn't seem to affect the scope of the graphs that are being generated. From the output generated from any given run, it seems like Doxygen itself is generating hundreds of graph files, and Graphviz is just faithfully generating graphs for each one. Is there any known way to make Doxygen generate one large graph file instead of hundreds of smaller ones?
Alternatively, are there any free visual graphing solutions out there which know how to handle complicated C++ project files with nested pre-processor directives, MIDL interfaces, and manually defined include paths the way Doxygen does?
My searches are finding general graphing utilities (or questions about them), but nothing specific to large C++ projects. Surely with all the coding that's been done over the years somebody must have such a tool!
Thanks,
-Alex
You can use the XML files generated by doxygen, and merge them into a single giant dot-format graph file (using xml stylesheet or similar), then run graphviz on it.
Doxygen automatically invoking graphviz is most useful when the number of graphs is high. For a single graph, automatically creating the content is important, but automatically calling dot, not so much.
We're creating very complex embedded system and «sources» contains few projects of Visual C++, IAR, Code Composer Studio and Altium Designer schemes and pcbs. All of that possibly could be in few versions.
So, what practice could you advice me to arrange all that stuff?
Thank you
I have the same setup as you.
I use Altium Designer for the hardware schematics and PCB design. But I also have Firmware source files and related utilities. And I have mechanical design files.
Here's how I do it:
Project Name
Firmware
MainCpu
trunk
tags
branches
IoCpu
trunk
tags
branches
Hardware
MainPcb
trunk
tags
branches
IoPcb
trunk
tags
branches
PowerPcb
trunk
tags
branches
Mechanical
Chassis
trunk
tags
branches
Other
trunk
tags
branches
This way all the project files are stored together in the SVN repository. The only down side I've found is that you can't just check out the Project and get the latest FW/HW/MEK files. You have to check out each Head of FW/HW/MEK.
The reason for the separate sub-modules for FW/HW/MEK is that they will get separate version tags.
Everything that you consider as sources should be under a Source Control System, like SVN. This is the best way to handle versions, revisions, branches and tags. SVN can handle binary files, so you won't have problems with non-text files.
If your C++ source files are numerous and span multiple directories then the effort put into grokking Large Scale C++ Software Design by John Lakos may be very worth it. The main theme of the book is how your physical layout of the software, that is, the arrangement of source code files in directories, limit or extend your ability to modify the software.
I like to have a directory structure that at the top level reflects each of the programmable parts.(i.e. microcontroller, DSP1, FPGA1, FPGA2,...)
I also like to have a subdirectory(ies) that has all the generated files, so it is easy to make a clean source tree. Also make it easy to do a clean build straight from the source code configuration tool. (i.e. get and build from source to binary image(s) in as few steps as possible)
Also have each programmable part have it's own version number, and one version number that reflects each of the combination of the sub component version numbers.
Definitely use source control, if the program itself doesn't support it, just keep the parent folder you use under source control. SVN is my current fav.
As far as how to arrange your files, I noticed you had Altium Designer on your list, that program will a) play nice with source control, and b) arrange your files in an orderly manner, assuming you use their whole 'project' file structure. Look into using their 'PCB' (if that's what your doing) or 'embedded' projects, when you create one, it creates buckets for you to store all your different types of files into.
Even if you don't want to actually use Altium for your files, create a project and look at their directory structure to get an idea about all the files you'll need to keep track of.
(Aside from trivial helper classes) put one class in each cpp/h file, and name the cpp/h files the same as the class.
Group related classes files into folders (you can optionally use a hierarchy of namespaces that match the folder structure. The .net approach here is to use a CompanyName.ProductName namespace, with your files stored in a ProductName project/subfolder of your solution). So for example, you might group your Math, I/O, and Drawing classes into separate "subsystem" folders.
Ideally, make these separate sections into re-usable libraries (MyCompany.Math). You'll be glad of this later when you want to develop a new product that will share some of the code. In that case, the top level "folders" become separate projects in their own right, and you can start to work on minimising dependences between them to realise and then enforce a much better overall framework design in your code base.
The ideal within folders is to find a good balance between clutter and sparseness - try to balance the folders so that they have between 5-15 files in each. If fewer, consider merging the folders; if greater, consider adding sub-category folders to break down the complexity.
As long as your classes/files and namespaces/folders have good descriptive names, and your folders are logically structured, you can make an extremely large project very easy to navigate.
At the risk of starting a religious war, I prefer to put the headers and their source files in the same folder so that when you are editing a .cpp the .h is easily accessible rather than having to move up and fown by a folder all the time.
Reduce the complexity!
My first engineering professor had a famous first lecture. It consisted of a single equation written on the blackboard:
Perfection = Simplicity
The problem with Source Control Systems is that they manage complexity but also promote it.
I have a substantial body of source code (OOFILE) which I'm finally putting up on Sourceforge. I need to decide if I should go with a monolithic include directory or keep the header files with the source tree.
I want to make this decision before pushing to the svn repo on SourceForge. I expect a lot of people who use it after that move will keep a working copy checked out directly from SF so won't want to change their structure.
The full source tree has about 262 files in 25 folders. There are a lot more classes than that suggests as due to conforming to 8.3 character names (yes it dates back to Win3.1) many classes are in one file. As I used to develop with ObjectMaster, that never bothered me but I will be splitting it up to conform to more recent trends to minimise the number of classes per file. From a quick skim of the class list, there are about 600 classes.
OOFILE is a cross-platform product expected to be built on Mac, Windows and assorted Unix platforms. As it started life on Mac, with compilers that point to include trees rather than flat include dirs, headers were kept with the source.
Later, mainly to keep some Visual Studio users happy, a build was reorganised with a single include directory. I'm trying to choose between those models.
The entire OOFILE product covers quite a few domains:
database front-end
range of database backends
simple 2D graphing engine for Mac and Windows
simple character-mode report-writer for trivial html and text listing
very rich banding report-writer with Mac and Windows Preview and Printing and cross-platform generation of text, RTF, HTML and XML reports
forms integration engine for easy CRUD forms binding to the database, with implementations on PowerPlant and MFC
cross-platform utility classes
file and directory manipulation
strings
arrays
XML and tag generation
Many people only want to use it on a single platform and some of those code areas are pure legacy (eg: PowerPlant UI framework on classic Mac). It therefore seems people would appreciate not having headers from those unwanted areas dumped in their monolithic include directory.
I started thinking about having an include directory split up into a few of the domains above and then realised that was sounding more like the original structure.
In summary, the choices seem to be:
Keep original model, all headers adjacent to source - max flexibility at cost of some complex includes in projects.
one include directory with everything inside
split includes by domain, so there may be about 6 directories for someone using the lot but a pure database user would probably have a single directory.
From a Unix build aspect, the recommended structure has been 2. My situation is complicated by needing to keep Visual Studio and XCode users happy (sniff, CodeWarrior, how I doth miss thee!).
Edit - the chosen solution:
I went with four subdirectories in include. I started trying to divide them up further by platform but it just got very noisy very quickly.
Personally I would go with 2, or 3 if really pushed.
But whichever you choose, please make it crystal clear in the build instructions how to set up the include paths. Nothing dooms an open source project more than it being really difficult to build - developers want a quick out-of-the-box experience and if it involves faffing around with many undocumented environment variables (or whatever) most will simply go away.