Request: More Examples

[JohannesMP]

While the Hello World script is useful to get a small taste for what premake can do, I feel that there simply are not enough examples for someone to look at to get an idea of how to use it for a real project.

While perusing the wiki can help you learn about new functionality that you may want to use in projects, it's often far nicer to see a complete and working project, and how they choose to structure their code.

Sure, there are other repositories out there that rely on premake, but their scripts are often huge, barely commented, and often use deprecated functionality, or are just too complicated for a quick reference. As often in computer science, there's an effective learning cliff from trivial to very complex, with very little in-between.

I understand that with every project, how you structure your premake5.lua is unique and depends on the developer's style, their project's needs, and target goals, but nonetheless I find myself wishing for a step a little above "hello world", something that shows good practices for a non-trivial, but still simple, cross-platform example.

Basically here is my wishlist:

• A single, well-commented premake5.lua workspace
• Two projects: A simple static library and a windowed application that dependson the library. Bonus would be having a 3rd project for unit testing.
• Cross platform, so it can compile for Mac and Linux with gmake, and for Windows with visual studio (2013 or later).
• It links to some dynamic library such as SDL2 or GLFW so it could even just be a simple "hello triangle" OpenGL program.
• On Mac it should wrap up the unix executable in an actual, correctly formatted .app application, including moving the dynamic library(s) to their respective folder(s) inside 'Contents' and adjusting the rpath accordingly.
• A dedicated wiki page that walks you through the rationale for the layout of each section would be ideal, but not necessary.

I feel that new users would really benefit from a "hello world 2" like this.

---

An alternative would be to just have add an "Additional Examples" wiki page that follows the 'Your First Script' section, with links to repositories of projects that are known to use premake5, that have been vetted for clean structure and good practices, and so are deemed useful as examples for someone wanting to learn more about what premake can be used for, or just wants inspiration for how they could improve their own projects.

[samsinsane]

Would you expect these examples to include actual source code, or would it just be the Premake scripts?

[JohannesMP]

I suppose to be able to see that it works actual code would be required, but it could be as simple as the 'hello triangle' demo you make when you first use something like SDL, GLFW, etc. enough to show that, yes, this does compile/work on mac/linux/windows, but the focus would definitely be on the Premake script.

Like, the project would be interesting enough to see a goof portion of the features that Premake has to offer, used in the context of actual (but basic) code.

[GabrielMajeri]

I've written such a tutorial, you can find it on the wiki. I only tested it on Windows, however, but it should work on other systems too.

It has 3 projects, including a unit-test one. It links statically to GLFW, and to the OpenGL DLL / Shared library. Feel free to add improvements to it.

[tvandijck]

That is a great example, and I thank you for taking the time to make that... I hope you don't see my feedback as negative, but there is a few minor things I personally would change, but I completely understand that this might just be personal preference...

• In my opinion "Static Libraries" should never link against another.. Not because it is wrong, but it does actually cause a build order dependency, and hence an inefficiency when doing distributed builds. Basically that means that the "useGLFW()" method is useful and handy, but shouldn't be used for the staticlib, or at least adjusted to look at the kind to skip the links { 'glfw3' }
• The use of cfg.configuration in the objdir/targetdir is perfect in this example, but fails if you added platforms { 'x86', 'x86_64' } to the workspace. Some explanation towards that would be awesome.
• And on that note, because you used the %{prj.name} token in the targetdir/objdir settings, these settings can actually be set in the workspace, and will automatically propagate to all the projects within that workspace. No need to call the setOutputDirectory for each project. The token will be expanded when the vcxproj/makefile gets written out, and hence will be unique to the project and configuration already.
• The dependson "ExampleLib" in the application is unnecessary... links already implicitly create that build order dependency. dependson is a keyword that is really only required to enforce order between projects that have no link dependencies on each other.. Which in the end is really only a useful keyword if you don't link all libraries against each other as mentioned in my first point.

Anyway, again, I think having tutorials like this is great, I'd love to see more... Is this tutorial accessible from the main wiki page?

[tvandijck]

I added it under tutorials, https://github.com/premake/premake-core/wiki/Tutorials with a link to that page on the main page under "Writing Premake Scripts"...

[GabrielMajeri]

Thanks for the suggestions! The truth is, I'm not very experienced with Premake, but I hoped the tutorial will be helpful anyway. I added your changes:

• I didn't realise tokens would be replaced for each project when you set them at workspace-level, thanks.

• I should've read the links { } documentation more carefully, I though dependson was necessary, it's fixed now.

• About the linking GLFW part: that was sort of a forced example, I wanted to show how a function is added in Premake, but I guess I'll look for a better example. It's removed now.

  I've created different functions, one for including Catch, one for including the ExampleLibrary etc.

[tvandijck]

The truth is, I'm not very experienced with Premake, but I hoped the tutorial will be helpful anyway.

Honestly, this tutorial is great... the changes you made are good... again, thank you for taking the time.

[Jarod42]

On my side, for testing purpose, I created https://github.com/Jarod42/premake-sample-projects

So there are samples for some features as a whole.