Re: tutorial building for "Learning Modern 3D Graphics

great news (at least for me) - after compiling for gmake and running the Tut 01 Hello Triangle i finally see this bloody white triangle on black font. Thanks to everyone Can finally start reading about OpenGL now.

all3fox: Did you post the complete compiler output, specifically: is there no message about a file not being found?

sorry i didn't notice that question at night. Yes, it was the complete output from codeblocks. No "file not found" or other messages.

Re: tutorial building for "Learning Modern 3D Graphics

Originally Posted by Alfonse Reinheart

You build that project, in both debug and release. Only after this step is complete do you go on to build TinyXML. And again, you must load the TinyXML workspace after using Premake, and again you must build it in debug and release.

Once that's done, you're ready to build the tutorials.

Hi again. In another thread you emphasized ease of use for your SDK. The above is why people typically ship binaries in a SDK. So that people with no deep investment in figuring out how to use stuff, can understand the essentials of what is offered without having to deal with build issues. Once people have made it past that point and decided a SDK is "worth it," of course the build should be easy to do, so long as one is willing to understand Premake etc.

Another reason for shipping binaries, is it proves that the SDK was buildable, at least at some moment in time. If binaries are released frequently, then it's proven at a recent moment in time.

Re: tutorial building for "Learning Modern 3D Graphics

I don't see how that would help in this case, since virtually no Linux-based library ships binaries. This is primarily because Linux binaries don't work very well on different machines. Even within the same distro, different machines will have different libraries and such installed.

When you're shipping something for a single platform like Windows, it's theoretically possible to ship binaries. When you're dealing with being multi-platform, it's simply untenable. On Linux, the most effective way to ship someone a library is as source code and let them build it themselves. Even on Windows it's non-trivial, as you need library variants for different compilers and such.

More importantly, this is a tutorial, not an SDK. The SDK is just used by the tutorial. And the build is less complex than it was before the SDK.

Re: tutorial building for "Learning Modern 3D Graphics

Originally Posted by Alfonse Reinheart

I don't see how that would help in this case, since virtually no Linux-based library ships binaries. This is primarily because Linux binaries don't work very well on different machines. Even within the same distro, different machines will have different libraries and such installed.

I'm not a Linuxer, I tend to try it every few years and run away. But your comment doesn't make sense to me, because I know there are distros, and people use them. People don't just spend all day rebuilding distros, unless they're serious tweakers who've just got to get that last optimization flag in there. So packages abound. Packaging on Linux is very modern compared to open source on Windows, where it's a joke (not counting Cygwin). Since I don't quite believe you, but I'm not really sure, I guess I'll go look for counterexamples of common libraries that have Linux packaging. Or even Linuxy ideas about SDKs. EDIT: Ok right didn't believe you. Ogre 1.7.3 SDK has a prebuilt Ubuntu package, research concluded.

Even on Windows it's non-trivial, as you need library variants for different compilers and such.

This I can speak to, because Windows is the primary open source drill I've done. Yes the work is non-trivial, but that's why a good SDK does the work, so that the consumers benefit and don't have to do it themselves.

More importantly, this is a tutorial, not an SDK. The SDK is just used by the tutorial. And the build is less complex than it was before the SDK.

Well admittedly I did not read the whole thread. I was just searching for all of your posts about glload to understand your SDK objectives. Half of the thread seemed pertinent enough, so I replied.

As for making a tutorial, I don't think the point is lost, however. Are you trying to teach OpenGL? Or are you trying to teach build systems? If the former and not the latter, it would be better to ship binaries and generated project files. My meager understanding is that premake4 can do that. You get standalone project files out the other end. Whereas the end results from CMake still have CMake as a final component.

Re: tutorial building for "Learning Modern 3D Graphics

Come on, Brandon J. Van Every, don't be that in love with shipping things in binary! Looking back on the build instructions for this particular tutorial i realize that everything was in its' rightful place so that to make the building process less painful. The fact that i kept failing meant only my lack of experience in building stuff which also means that i've learnt something.

Are you trying to teach OpenGL? Or are you trying to teach build systems?

both, sure. And that's a huge plus not a minus as you try to convince us. A plus because everything is decently documented.

Re: tutorial building for "Learning Modern 3D Graphics

Originally Posted by all3fox

The fact that i kept failing meant only my lack of experience in building stuff which also means that i've learnt something.

I suppose it's good that you value a learning curve, but many people don't. Either because they have too little experience, or they have too much experience. If you want the maximum uptake for something, make it as easy as possible for people to get going.

Re: tutorial building for "Learning Modern 3D Graphics

That certainly is a package. But I don't see the "prebuilt" part. As I understand it, PPAs for libraries are perfectly capable of doing the building as part of the install process.

Also, Ogre isn't a tutorial; it's an SDK. You need to be able to build tutorials, because you will want to play with the example code. Thus, shipping a build process with full source code is very important.

As for making a tutorial, I don't think the point is lost, however. Are you trying to teach OpenGL? Or are you trying to teach build systems? If the former and not the latter, it would be better to ship binaries and generated project files.

A tutorial is not a series of programs that you run to see cool stuff. That's called a demo or example code. That's what you get from here (no offense intended; example code is important, for the purpose that it serves). Tutorials exist to do something very different. The most important parts of a tutorial are, in this order:

1: The text that explains how it works. Without this, actually learning why the particular code is where it is becomes virtually impossible.

2: The code that implements it. The salient points are covered in the text, but it's always nice to see the full code example.

3: The compiled binaries that show what the tutorial does. Without this... well, you could look at the pictures embedded in the text of the tutorial and follow along with little problem.

In short, the need to actually run the code is a distant third on the scale of "what actually matters for learning." Sure, you need to be able to build the projects to do the exercises at the end of the chapters. But in terms of following the tutorial itself? Not the most important thing in the world.

Does Premake4 allow you to ship build files? Sure. But the whole point of it is that you don't have to. They can make the build files for their particular build system with a single command line. If someone still uses VC6, they can get their project files. If someone uses Code::Blocks, they can get their workspaces. If someone loves Make, they can get makefiles.

Here is a list of the possible combination of OS and build files that I support by shipping a simple Premake4 script:

That's thirteen separate build options. And since many of these use the same filenames, I would have to generate these into separate directories, thus creating 13 separate directories for each of the (currently 16) tutorials, the SDK, and TinyXML. That's a lot of clutter to look though, especially since each user is only going to be looking for their particular build tool.

Or I can just ask the user to type a simple command-line. A process that I take time out in the text to actually explain. This is not a Herculean effort requiring god-like strength. It's "premake4 platform", where `platform` is well-defined by a direct link to the Premake documentation. That's how Premake is intended to work.

That's the thing: we are not talking about an onerous process. We're not talking about forcing people to have to cobble together a build from loose files and some overly-simplistic directions (see the Lua distro if you want to see a really crappy build process). We're talking about one command. Execute it once, and you get your build files.

There are levels to "ease of use". Currently, I would say the tutorials and the SDK are "reasonably easy". I simply do not feel that attaining the level of "ease of use" you're talking about is worth the time, effort, or the problems that come along with it (large downloads. Shipping 10 separate windows binaries for 45+ executables in debug and release isn't small. Not to mention DLL-hell, since you keep wanting those).

I took that comment at face value. I don't know if it's true. I'm not a Linuxer, you can go test it. Even if it isn't prebuilt, it's claiming that you invoke one apt command and you're done. That's how things should be. No work, you're a build system, do it for me.

In short, the need to actually run the code is a distant third on the scale of "what actually matters for learning."

Only you say so. Everyone else wants to know that their learning curve isn't going to be a pointless waste of time. Clicking on a prebuilt binary sets a goal: this is what you're aiming to complete.

Does Premake4 allow you to ship build files? Sure. But the whole point of it is that you don't have to.

No, that's not the whole point. The point is you can make one build description that's cross-platform, cross-IDE, written in a sane language, and produces standalone build files. Actually, "the point" doesn't have to include all of that. I'm mainly interested in the sane language, I'm not going to learn MSBuild. If you don't want to ship binaries that's your point, not "the whole" point.

If someone still uses VC6,

then maybe they should be in a nursing home. Ok ok, maybe part of the Space Shuttle runs on VC6. Wait, they retired those. Ok! Some part of someone's ancient OpenGL infrastructure somewhere actually runs on VC6, and it's crucial to national security. I'm sure someone does it but it's not what I'd call an important case use.

That's thirteen separate build options.

Welcome to build engineering. ;-) It's a good practice to support all the ones that are mainstream. Do you want to talk about automated nightly builds and test suites?

That's a lot of clutter to look though,

The world manages. Go look at some of the bigger CMake driven open source projects.

Or I can just ask the user to type a simple command-line. A process that I take time out in the text to actually explain.

I think one verdict on that was had at the beginning of this thread. You "solved" the problem by insisting that someone RTFM. He got angry. Regardless of the ethics or morality of it, it says to me your approach is not as simple as you claim.

Look all we're actually arguing about at this point is how much work you personally care to do. Your gruntwork vs. how much you want people to utilize your SDK. If you want maximal adoption, you can adopt the practices that the largest, most popular cross-platform open source projects use.

Re: tutorial building for "Learning Modern 3D Graphics

Only you say so. Everyone else wants to know that their learning curve isn't going to be a pointless waste of time. Clicking on a prebuilt binary sets a goal: this is what you're aiming to complete.

Yeah, I guess you're right. I mean, I'm obviously a fool for spending all that time writing over three hundred pages of text, spending hours making charts and diagrams to explain points. Editing passages to make sure they're clear to a new user. Rearranging text so that each topic flows properly into the next, so that each tutorial builds on and properly reinforces its predecessors. That was a complete waste of time for a project intended for someone to learn from.

I mean, who needs detailed explanations for things when you can just ship binaries? I mean screw that whole teaching people how to use shader-based OpenGL; we've got to get some friggin' binaries out to people!

Oh, and if you're saying that you were talking about my SDK and not the tutorial, don't bother. You clearly said, "As for making a tutorial, I don't think the point is lost, however. Are you trying to teach OpenGL? Or are you trying to teach build systems? If the former and not the latter, it would be better to ship binaries and generated project files." And my point was that building the code is not the most important thing for learning with my tutorials.

No, that's not the whole point. The point is you can make one build description that's cross-platform, cross-IDE, written in a sane language, and produces standalone build files. Actually, "the point" doesn't have to include all of that. I'm mainly interested in the sane language, I'm not going to learn MSBuild. If you don't want to ship binaries that's your point, not "the whole" point.

Similarly, your interest in "the sane language" is also not "the whole point". It's a good point, but only using Premake4 because it's a nice build language misses a lot of its utility.

I use Premake4 as a way to support build systems that I have neither the time nor inclination to use. That's the whole point for my projects. It's a clean way to allow the user to pick their favorite build tool.

We have different needs. That's fine. What makes your needs so much better than mine?

then maybe they should be in a nursing home. smile Ok ok, maybe part of the Space Shuttle runs on VC6. Wait, they retired those. Ok! Some part of someone's ancient OpenGL infrastructure somewhere actually runs on VC6, and it's crucial to national security. I'm sure someone does it but it's not what I'd call an important case use.

And that's the whole point. You believe that VC6 users are not "an important case use".

I don't agree. The thing I hate the absolute most when working with Open Source projects is being told what build system to use. I hate projects that don't come with Visual Studio builds (or something that can generate them, like CMake/Premake). I hate the arrogance of OSD people who think that Make is all everyone should use, and screw those Windows developers for their fancy IDEs; just use VI like everyone else.

I don't use VC6. And I don't think that people should. But I do not believe it is my right to tell them that they shouldn't. I will make no special effort to ensure my code compiles on VC6; it is not officially supported. But I will also make no special effort to stop them.

If someone hates VC7+, who am I to say that they're wrong? Who am I to say that they shouldn't have a build system where they use VC6 as their IDE (and therefore need VC6 project files), but they actually hook into VC2010's compiler via various means? I may not use VC6, but I will not deliberately hurt them if I can avoid it.

Yes, I don't support every possible IDE. But I do use Premake4, which supports a hefty number of builds. That is, as far as I'm concerned, doing diligence as far as supporting builds.

I will make my projects available according to the values to which I hold. I believe that a project should be self-contained, affecting as little as possible on a user's system. I believe that a project should have a build system that accommodates the user's preferred tool path as much as possible, not tell them how to build their stuff. And yes, I believe that the build system should be reasonable straightforward and centralized as much as possible. Premake4 offers that.

I think one verdict on that was had at the beginning of this thread. You "solved" the problem by insisting that someone RTFM. He got angry. Regardless of the ethics or morality of it, it says to me your approach is not as simple as you claim.

That is not a reasonable conclusion given the available evidence. This thread contains exactly three people who ran into a problem. Two of them were easily and quickly helped. One of them could not be helped because he refused to actually say what the problem was in a reasonable way.

The only way to know whether the process is "as simple as (I) claim" is to match the number of build failures to the number of successes. Since neither of us has any particular knowledge of how many build successes I've had (I can give you download stats of around a thousand or so for the SDK, and half that for any given version of the tutorials. But a download does not necessarily mean a success), any attempt at a factual statement one way or another is false.

Trust me: people like `tyro1` exist. And they will have problems with the simplest install procedure. No matter how foolproof you make a system, someone will be a bigger fool. You can only look to how many people successfully use the system vs. failures.

And people for whom the system works don't need to make posts or file bug reports.

If you want maximal adoption, you can adopt the practices that the largest, most popular cross-platform open source projects use.

Which:

1: is no guarantee of "maximal adoption".
2: requires more time than I care to invest.
3: requires doing things that are against my personal beliefs.

Thank you for the advice. But I'll keep going with what I have, if it's all the same to you.

Of course, there's nothing stopping you (or anyone else) from using the existing distro to make and distribute binaries if that's what you really think would help. Many, many projects work this way, where the primary developers make the real code and others create various binary distros and such for those who want simpler installations (though most of the time, it is for much more complicated build systems).

In fact, if you took the time you spent writing messages and spent it on "build engineering" for my current SDK distro, I bet you'd have a couple of binary packages available by now

I'm not going to do it. The only reason the SDK even exists is because it's derived from my tutorial framework. I felt that I could wrap it up in a nicer package and let people use it directly. If it helps someone, great. If it doesn't, that's fine. But I've invested about as much attention on having a reasonable build system as I'm going to.

Re: tutorial building for "Learning Modern 3D Graphics

Only you say so. Everyone else wants to know that their learning curve isn't going to be a pointless waste of time. Clicking on a prebuilt binary sets a goal: this is what you're aiming to complete.

Yeah, I guess you're right. I mean, I'm obviously a fool <snip>

Alfonse, here is my constructive feedback about your approach to all these things. You are a man of very strong, distinct opinions about how anything "should be done." I'm pretty sure this blinds you to other people's modalities of engagement. Whether it's a newbie in this thread trying to use your stuff that gets angry about how you speak to him, or some other person with an idea about opengl32.dll that you give a harsh critique to, or other such as I've seen in these forums while researching your posts and coding efforts. You have a lot of energy and drive, and sometimes you have good engineering taste. Other times you just have "your" engineering taste, and it seems like you haven't spent much time in other areas of public engineering practice. Maybe you took issue with something at some point and decided your way was the "right" way. It really doesn't matter, as you're the only one who's going to work on your tutorials and SDK, so long as you insist on your idiosyncracies. I'm just trying to tell you how other people see things; I can't make you see or agree.

We have different needs. That's fine. What makes your needs so much better than mine?

I've been trying to figure out if you have any popularity goals typical of SDKs. I conclude that you don't. There's a certain way that people bob and weave when they're trying to get everyone to adopt their stuff.

And that's the whole point. You believe that VC6 users are not "an important case use".

I don't agree. The thing I hate the absolute most when working with Open Source projects is being told what build system to use.

That's a rather emotional, theoretical, ideological objection. How many VC6 users are actually out there now? It's open source, they can code it up themselves if they want something particularly weird. Open source is supposed to be a profitable activity. It's not profitable if you're doing lots of extra work for weird corner cases that very few people actually need. By "profitable" I mean that anyone's effort should be weighed against the $X/hour they could be making doing something else.

One of them could not be helped because he refused to actually say what the problem was in a reasonable way.

Actually he could be. You just didn't want to do it on his terms. "I wrote TFM; you must RTFM." Well, maybe TFM isn't as good for a newbie as you believe it to be. Sure you asked him what he thought was wrong with TFM, but you were testy and standoffish about it. As though you really didn't want to hear that there was something inadequate about it, and just wanted him to get with the program and do his homework.

In fact, if you took the time you spent writing messages and spent it on "build engineering" for my current SDK distro, I bet you'd have a couple of binary packages available by now

You're not the kind of project leader I'd hitch my wagon to, frankly. More like a code fork if I cared enough to solve OpenGL's problems. I don't know that I want that job. Thanks at least for licensing your code sanely; none of the other extension wrapper projects do.

The only reason the SDK even exists is because it's derived from my tutorial framework.

Well that explains a lot, if the tutorials came first. You're into writing tutorials, not SDKs.