Single Header Generation

[ghost]

It would be really convenient to have this library as a single header file. There's a couple of tools that can generate single header files from a list of sources. If you added a script for this, perhaps in a CI step or just by itself, it would make integrating this library into other projects very easy.

The opinions about single header distributions are a mixed bag, but there's little doubt that they're very convenient.

Here's a link to a python one, called Quom: https://github.com/Viatorus/quom

[szellmann]

Acknowledged. I'm personally not a huge fan of them as dragging everything in means you actually drag every possible problem in along. Still, if it were just an option that the user can choose from I'd be very open to it.

You happen to know an example where deployment with such a script is done using CI? The commonly used CI services seem pretty confined to the VM they're running in, though I see ways to do this with Travis and the like. Perhaps with gitlab-ci one could do this on a personal machine but that would not be feasible for me.

[ghost]

Unfortunately not at the moment. Travis CI and Appveyor can both deploy build artifacts to GitHub releases. If you have a GitHub page, you can also deploy them there as well.

Having done both types of deployments, I personally think that the deployment to GitHub pages is easier if you already have a page up, because you can also deploy it with any Doxygen generated documentation.

If you'd like, I can just submit a PR for it. Or, since I plan on doing this with another template library, I can send you an example once it's done.

[szellmann]

I'm thinking that the most convenient thing to do (regarding my laziness when it comes to release management) would be to have Travis CI deploy the composed header to the repo itself (I'm a bit reluctant to set up an official github-io page as that would require at least some maintenance which at the moment I'd like to avoid).

On this travis docu page it says that

Travis CI can automatically upload assets to git tags on your GitHub repository

but I'm not totally sure what that means, my understanding was that a git tag was more or less just a token used to mark a certain commit. When I'm understanding this correctly, setting on: tags: false would actually cause Travis CI to deploy the "FILE TO UPLOAD" on any commit?

[ghost]

I believe that's a slightly misleading statement in the Travis CI documentation. It doesn't upload assets to tags. You're right about the tag just being sort of a token. On GitHub, tags are typically considered releases and so it allows you to associate "assets" with the tag. An asset might be a tarball of the source code, executable, etc. This feature is usually referred to as "GitHub Releases" in Travis CI as well as AppVeyor.

Unfortunately, I just tried to give this a shot with an automatic deployment script in another repo and found it to be quite cumbersome.

I gave Quom a shot, but it goes into an infinite loop when generating a header for this library, generating hundreds of thousands of repeated visionaray code.

I gave another tool a shot. It required having a hand written header, which was not too unreasonable. Ultimately though, it did not remove any of the headers with '<' and '>' because it considered them to be system headers. In visionaray, there seemed to be quite a bit of project headers included that way. I certainly wouldn't suggest changing them for a tool like this, either.

I think this ended up being a little less automated than I originally thought. I no longer would advocate for this idea.

[szellmann]

I'm wondering if a C++ preprocessor (thinking maybe clang) would be the right tool to generate such header. Will play with this myself a bit later.

I tend to include via <> as a convention that those headers are in the include path and headers from the same directory shouldn't override. I could imagine adopting this convention though.

[szellmann]

(this would of course require the preprocessor to only trigger on the #include statement, that's probably not feasible)

[ghost]

Doing it with the C preprocessor would work, but would have to differentiate system headers from project headers with preprocessor magic, so that you don't include system headers in the single header library.

#ifndef VSNARAY_SINGLE_HEADER
#include <vector>
#include <utility>
/* etc */
#endif

And then make a dedicated single header template.

#pragma once

/* include required system headers */
#include <vector>
#include <utility>

/* insert code generated by `g++ -E -DVSNARAY_SINGLE_HEADER=1 visionaray/*.h` */

But that's just speculation. There might be other issues I can't think of. This would also be very invasive to the code base in that it would require many uses of #ifdef VSNARAY_SINGLE_HEADER

Ah, you're right about only triggered on #include. Good point. I don't think this would work either.

[szellmann]

I fear there's no way to prevent it from evaluating all the other macros (not just the includes) as well. Contemplating this a bit more. I see that single-header would make the library more accessible.

[ghost]

I'll admit, it certainly makes distribution easier. Let me know if you decide to take this route and if there's anything I can do to help.