Just adding some documentation triggers recompilation: Is there a solution?

Question

Sometimes, when I look through my header files I'd like to add something little to the (doxygen) documentation. That might be a quick note about the use of some function parameter, or just fixing a little typo.

But then I think: Oh no, that'll trigger a recompile on the next make call! And for certain basic headers the whole project would recompile, which can take a long time. So, nevermind!

Is there a solution to this dilemma? Are there approaches where the functions/classes are documented not directly in the headers? Or are there (plans for) a smart make that would notice that only some comment has changed, but no recompilation is necessary?

Answer 1

Why not just touch the file back to a time where make won't think it changed?

As onebyone suggests you could wrap it into a simple script.

Answer 2

You could shorten the compile times using ccache, possibly with the CCACHE_UNIFY environment option set.

ccache hashes the pre-processor output, and serves the previously compiled object if no changes were detected.

Man page section about CCACHE_UNIFY

CCACHE_UNIFY

If you set the environment variable CCACHE_UNIFY then ccache will use the C/C++ unifier when hashing the pre-processor output if -g is not used in the compile. The unifier is slower than a normal hash, so setting this environment variable loses a little bit of speed, but it means that ccache can take advantage of not recompiling when the changes to the source code consist of reformatting only. Note that using CCACHE_UNIFY changes the hash, so cached compiles with CCACHE_UNIFY set cannot be used when CCACHE_UNIFY is not set and vice versa. The reason the unifier is off by default is that it can give incorrect line number information in compiler warning messages.

Answer 3

Just make the changes, and accept the recompile. It's not really possible to have a functional development environment when the devs are afraid of compliation; perhaps you need to look into a distributed grid compilation system that will reduce the compilation time?

Answer 4

make works strictly from the timestamps on the files, and there are definitly no plans to extend it past that. make is used for a lot of things besides just C, and doesn't know anything about the contents of the file. Your build would probably get a lot slower if make had to analyze the changes.

You can keep your documentation out of your header files and just in the .c files, which will limit the scope of what needs to be recompiled. I'll admit that personally I prefer to document "interface" functions in header files, but from doxygen's standpoint it doesn't really matter.

As suggested by another, you can bypass this system by using 'touch' to back-date a file.

doxygen will let you put comments in external files, but that's generally an undesireable solution; part of the whole point of doxygen was to keep the documentation close to the source.

Otherwise, I suggest you fix your compilations to be faster... you really shouldn't be afraid of them.

Answer 5

My solution is to simply not include headers as dependencies in the Makefile... so changes to a header file do not trigger any recompilation by "make".

Of course the downside to that is that if I make a change that affects memory layouts (e.g. adding a member variable to a class) I need to remember to manually touch the affected .cpp files (or if it's too difficult to figure out which cpp files are affected, do a "make clean; make"), which can be a bit error prone... but it generally works for me.

Answer 6

How about checking out (you do version control, don't you?) another copy of the codebase in a different directory, just for these kinds of edits?

It can be a separate branch, or not. Then, when these kinds of small changes occur to you, you just make them here. You can commit them directly: now they are in a safe place, and won't disturb your actual development. Every once in a while, like once a week if your build times really are that long, you can merge these changes to what you are working on. Merge conflicts should rarely occur, as long as you document in one directory and write code in the other.