System Docs Page example is wrong

[OlekRaymond]

The example in the docs page throws an error and is not the correct way to use system The example given results in a error during any action:

workspace "MyWorkspace"
   configurations { "Debug", "Release" }
   system { "Windows", "Unix", "Mac" }

   filter "system:Windows"
      system "windows"

   filter "system:Unix"
      system "linux"

   filter "system:Mac"
      system "macosx"

Should be something more like this... (from what I can tell)

workspace "MyWorkspace"
   configurations { "Debug", "Release" }

   filter "system:windows"
      -- some items

   filter "system:linux"
      -- some items 

   filter "system:macosx"
      -- some items

[Jarod42]

I think example expected to be:

workspace "MyWorkspace"
   configurations { "Debug", "Release" }
   platforms { "Windows", "Unix", "Mac" }

   filter "platforms:Windows"
      system "windows"

   filter "platforms:Unix"
      system "linux"

   filter "platforms:Mac"
      system "macosx"

[OlekRaymond]

That seems counter intuitive: setting the system based on what configuration you choose

I double checked and it seems you not only filter with system but also set it, you can see why some documentation is needed.

Assuming that the given example doesn't allow you to run configuration "Mac" on windows I would be okay with this (along with a better description)

[Jarod42]

Remember you can generate solution for other platform/system/os/architecture. So with this exemple, you might generate a unique solution usable on all 3 systems (when using appropriate configuration/platforms).

doc should mention what does system impacts (I would say token replacement (as %{copy}) and path separator).

[OlekRaymond]

you can generate solution for other platform/system/os/architecture.

Guess that makes sense if I was building on wii or something similar.

Does system default to the system I am currently on or does it have a "constant" default (like always linux) and if so is there a good way to change my default configuration based on system as that's what would most benefit me at the moment.

I agree with your suggestion, the docs should contain: what system does, what it defaults too (assuming we don't supply an os argument when creating files) and when you would want to filter on system

[Jarod42]

I would say default is current system normally (Not sure if action does/might override that). I have personally never used "system". (And I build on ubuntu/macosx/windows).

[samsinsane]

For me, a better example for system would be showing that you can hardcode the target system. So, you might be developing an application for Android, and you don't care what platform you're on, you're always building for Android. premake5 vs2022 and premake5 gmake2 will always generate files that build Android binaries, no matter what operating system you're on.

What do you guys think? Does this work as a better example of how system can be used, and what it does?

and when you would want to filter on system

A possible example could be, you want to allow users to upload content straight to an AWS S3 bucket or Azure Blob container from your Windows application but only consume that content on your Android and iOS applications using HTTPS. So, you'd do something like:

filter { "system:windows" }
  includedirs { "<path/to/cloudsdk>/include" }
  libdirs { "<path/to/cloudsdk>/lib" }
  links { "<cloudsdk>.lib" }
filter {}

Though this example might be a bit convoluted, and perhaps a better example would be using different graphics libraries? DirectX, Metal, OpenGL and/or Vulkan. Something like this:

defines { "USE_OPENGL" } -- Set default
filter { "system:windows" }
  removedefines { "USE_OPENGL" } -- Remove default
  defines { "USE_DIRECTX" }
filter { "system:macosx" }
  removedefines { "USE_OPENGL" } -- Remove default
  defines { "USE_METAL" }
filter {}

Thoughts?

[OlekRaymond]

I think this too is confusing as you can use openGL on multiple platforms (including windows). The whole reason I started this thread was because finding the python so/lib/.h file was a real pain on linux and windows, maybe that would be a better example? It would look something like this:

filter { "system:windows" }
  links { PythonLibWindowsPath }
  includedirs { PythonWindowsIncludePath }
filter { "system:linux" }
  links {  PythonLibLinuxPath }
  includedirs { PythonLinuxInludePath }
filter {}

The reason we did this over just having multiple platforms was because in visual studio it defaulted to unix which was rather annoying.

[Jarod42]

I think that doc page should focus on system meaning, not on filtering.