I noticed that juce_amalgamated.h (from the tip) has lost most of the comments.
May I ask you (Julian) why?
One of the reasons I love Juce is because of its nice documentation within the code.
Amalgamated files are evil. Don’t use them while developing.
The issue you’re seing is probably due to intellisense or visualassist that resolved the method definitions location from the included amalgamated file. This incurs a huge memory cost while parsing for such tool, meaning slow code navigation, so don’t use amalgamated files while developing.
They are not made for you to read, but for the compiler (and the compiler don’t care about comment). So don’t use them while developing.
If you either modify the Juce source code, chances are high that you’ll forget to rebuild the amalgamated files, and you’ll get very frustrating debugging crazyness going on (like structure starting to behave strangely, like missing members, and so on). So don’t use them while developing.
IMHO, the only advantage of amalgamated files (if there is any) is when you’ll send your project for someone for compilation, you don’t have to send all juce’s headers. But except for that case, don’t use them.
They’re great for compile/link speed, and sharing a project, but for actual development [especially debugging], it’s a lot more practical to just use the library project.
It’s a trade-off, really. On one side there’s the convenience of not needing to have a separate project or build step, and it tends to build a bit quicker. However, the party on the other side of the fence has better debugging and a bouncy castle.
Ok, thanks.
I used the amalgamated for the last year, and I noticed that after the git move all the comments disappeared.
Yes, the amalgamated is of course faster for the compile process and not intended for reading.
But is also one single file, and after such time I’ve become used to it.
I would really like to see numbers here. Link speed with be exactly the same as with a lib (it might be a bit faster with a lib as lib have indexes, while binary object doesn’t)
About compile time, I agree it’s faster, as the compiler will mostly work on a big cache with amalgamated file, while it’ll waste time filling/emptying the cache with a pletora of small files.
However, you’ll (usually) compile once, and link multiple time, so the benefit doesn’t seems obvious to me.
And if you ever change your project defines or options then you’ll have to recompile the amalgamated file, while you wouldn’t with a lib.
For the risk/advantage ratio, it’s clearly not worth it.
I’ve lost numerous days trying to debug memory corruptions due to bad sync’d amalgamated files, not counting the chicken & egg issue it creates (try to build the amalgamator in the GIT for example), the slowness it adds to code parsing tools like visual assist/intellisense/ctag that are clearly not made for a 10MB header files.
The only other project I know that use this kind of trick is sqlite, but they still build a lib out of the single .c file.
The documentation of SQLite is not embedded in the code, so in all cases, you never actually have to open an header.
I must say I like the juce_amalgamated files, it is very convenient to have all of juce stuffed into one file. Even for tracking bugs or understanding an issue. I’m now using a modified version of the amalgamator since I find the doxygen comments to be very useful in the amalgamated files.
Do you guys really find it useful to have the comments in there? I’m surprised, because I never look inside the amalg files myself, I always just flip over to the juce project when I need to look something up, because it’s easier to find things there.
I took the comments out because it reduced the file size significantly, which made it quicker for clunky editors like XCode to open them when debugging. But if people really want them in there, I could put them back, I don’t really have strong opinions on it either way.
In my case the comments could be useful:
I’m starting a project with a friend who never worked with juce before.
We exchange projects often, using the amalgamated (so if we change something in the library we just need to exchange 2 files).
I’m used to juce, but my friend is not.
So, without adding the comments to the official amalgamated,
how can I rebuild the amalgamated lib including all comments?
You’d have to hack the amalgamator to stop it removing them.
Thank you