Entt: Help wanted: updated build system

[skypjack]

Thanks to @m-waka and his PR (#87), we have finally an updated build system.
Not only modern C++ from now on. EnTT offers also a modern CMake approach.

This lighting issue is to ask you all if you can test the branch experimental and look for issues to fix before to merge everything on master.
experimental tracks the master branch and adds to it only the new cmake stuff, so do not expect breaking changes if you are already using master.
@m-waka is a kind person and I'm pretty sure he will answer all of your questions about it, if any.

In 24/48 hours I'll close the issue and merge experimental on master if no bugs pop up.
Thank you all in advance for your help and I hope you'll enjoy this massive update to the CMake stuff.

[Kerndog73]

I just tried this on my system:

git clone -b experimental --single-branch https://github.com/skypjack/entt.git
cd entt/build
cmake .. -DBUILD_DOCS=YES

The script finds Doxygen but it's missing the dot component.

Found Doxygen: /usr/local/bin/doxygen (found suitable version "1.8.14", minimum required is "1.8") found components:  doxygen missing components:  dot

The previous script didn't find Doxygen, so it was downloading Doxygen (presumably with Graphviz). Or maybe it didn't need Graphviz? I don't remember. This script is finding Doxygen that I have installed with Homebrew which isn't built with Graphviz. So I did this:

brew uninstall doxygen && brew install doxygen --with-graphviz

And tried again.

Found Doxygen: /usr/local/bin/doxygen (found suitable version "1.8.14", minimum required is "1.8") found components:  doxygen dot

This time it worked without a hitch.

I'll have to make a few minor changes to the Homebrew formula so that it depends on doxygen --with-graphviz when the --with-docs option is passed and also pass -DBUILD_DOCS=YES to CMake.

---

The doxygen output is very verbose. There's a whole lot of status messages like this:

Generating member index...
Generating file index...
Generating file member index...
Generating example index...
finalizing index lists...
writing tag file...
Running dot...
Generating dot graphs using 5 parallel threads...
Running dot for graph 1/51
Running dot for graph 2/51
Running dot for graph 3/51

Is there something that can be done about that?

Among all of the status messages from doxygen, there were a few warnings. I don't think they're too important but here they are:

Scanning dependencies of target docs
warning: Tag `CLANG_ASSISTED_PARSING' at line 1034 of file `/Users/indikernick/entt/build/doxy.cfg' belongs to an option that was not enabled at compile time.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u", or recompile doxygen with this feature enabled.
warning: Tag `CLANG_OPTIONS' at line 1042 of file `/Users/indikernick/entt/build/doxy.cfg' belongs to an option that was not enabled at compile time.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u", or recompile doxygen with this feature enabled.

(lots of status messages)

Generating index page...
/Users/indikernick/entt/README.md:3: warning: Unexpected html tag <img> found within <a href=...> context
/Users/indikernick/entt/README.md:4: warning: Unexpected html tag <img> found within <a href=...> context
/Users/indikernick/entt/README.md:5: warning: Unexpected html tag <img> found within <a href=...> context
/Users/indikernick/entt/README.md:6: warning: Unexpected html tag <img> found within <a href=...> context

---

I updated the homebrew formula (locally) to use the new build system for the docs but it's getting some errors that I'm not getting outside of Homebrew. CMake seems to have a slightly different output when running under homebrew. It does things in a slightly different order, which is weird. I'll let you know when I figure out how to fix it. If I can't get it to work then maybe I'll remove the --with-docs option from the formula. The vcpkg package doesn't build the docs so I guess the Homebrew formula doesn't really need to. The docs are in the code, you can just read the code! :)

Side note: Is anyone actually using the Homebrew formula? If so, are you using the --with-docs option?

[skypjack]

@Kerndog73

I'll have to make a few minor changes to the Homebrew formula so that it depends on doxygen --with-graphviz when the --with-docs option is passed and also pass -DBUILD_DOCS=YES to CMake.

Can you make those changes? I've not a working machine on which to test it unfortunately.

The doxygen output is very verbose. [...] Is there something that can be done about that?

Probably yes, there should be a _silent everything_ option somewhere.

Among all of the status messages from doxygen, there were a few warnings. I don't think they're too important but here they are:

I think they depend on your compiled version of doxygen. In fact, they are saying that there is an option that requires a flag at compile-time that wasn't used to compile your version of doxygen. Indeed it suggests you to recompile doxygen among the other possibilites.

I updated the homebrew formula (locally) to use the new build system for the docs but it's getting some errors that I'm not getting outside of Homebrew. [...] I'll let you know when I figure out how to fix it.

Sure. Do not hesitate to ping me if I can help you somehow.

[m-waka]

With the change building the docs requires the CMake option BUILD_DOCS. When building with it the docs are built together with the ALL target. So no need for an extra make docs command. However you can still rebuild the docs or build only the docs using make docs. CMake options are to be set to ON or OFF following the official documentation but the if command also accepts other values like YES so you can leave it that way.

The output of Doxygen can be controlled in the doygen config file setting e.g. QUIET=ON:
http://www.stack.nl/~dimitri/doxygen/manual/config.html#config_messages

[Kerndog73]

I've been messing around with the Homebrew formula for about an hour. I think I'm just going to remove support for building the docs. :(

[m-waka]

What are the problems? Can I help you somehow?

[Kerndog73]

@m-waka The problem is that Homebrew sets some environment variables and shims a few things. This messes some stuff up. The CMake script works perfectly when invoked by me.

[m-waka]

@Kerndog73 okay as I have no Mac system available I probably cannot help you with this. But actually there is no big change in the doxygen stuff. So I don't see what's causing this now.

Just a side note: As the CMake scripts now include configuration files and install targets, packet managers should use these by e.g. make install or cmake --build . --target install. If you want to use a different location for the install command you can specify it as a CMake option, e.g. create an install folder within the build directory containing all the installed targets: cmake .. -DCMAKE_INSTALL_PREFIX="./install" for just shipping the library you can probably also use -DBUILD_TESTING=OFF as the external projects currently also end up in the install location...

[skypjack]

@Kerndog73 Is it ok to merge this on master anyway? I mean, set aside the doc, everything works fine for you when using experimental?
Because I'm out of home until Sunday and I don't have my laptop with me, I think I'll merge the two branches when I'm be back home. So keep your time to reply if you want to test it. :-)

[Kerndog73]

CMake is not to blame for the problems I’m having. My incompetence and Homebrew’s complexity are to blame. The build system works like a charm for me when Homebrew isn’t involved.

Merge if there aren’t any other problems.

[Kerndog73]

@skypjack I had another play around with this just now and I think I fixed the Homebrew formula! The Homebrew formula now uses this new build system to build the documentation. I'll push my local changes when the next version of EnTT is released.

@m-waka Thank you for your advice, it actually helped quite a bit. Part of the installation step is done by cmake.

[skypjack]

Great @Kerndog73 !!
Where is your incompetence now? ;-)
I knew it was only a matter of time.

---

So far, so good. I'm out of home till Sunday.
Because it seems that everything works just fine for everybody as expected, I think I'll merge it on master as soon as I'm back home.
I'll create also a new tag for this.

Thank you @m-waka for your help. Really appreciated.

[skypjack]

No news, good news. Ready to merge from my point of view. Thank you all for your help.

[skypjack]

Upstream as master.

[skypjack]

@m-waka I just noted this. Did you consider the install clause for the 'docs` target in your refactoring? Not sure about it, sorry for the annoying question.

[m-waka]

@skypjack This fine and installs the Doxygen documentation into the CMAKE_INSTALL_PREFIX location in subfolders share/entt-2.6.1.
We could also use the Variable CMAKE_INSTALL_DOCDIR from the GNUInstallDirs package which targets to DATAROOTDIR/doc/PROJECT_NAME. (DATAROOTDIR defaults to share) I don't know of any Windows specific convention where to install the docs, perhabs installing just to doc could be an option?

[skypjack]

@m-waka Unfortunately I don't know as well what could be the best approach on Windows. I'd suggest to leave it as it is and let's see if someone pops out in future asking for changes. :-)