Updated documentation for premake generator (#4090)

* Updated documentation for premake generator

Added premake toolchain generator and updated documentation according to
new changes

* Added shared option note

* Update reference/tools/premake/premaketoolchain.rst

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

* Apply suggestions from code review

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>
Co-authored-by: James <memsharded@gmail.com>

---------

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>
Co-authored-by: James <memsharded@gmail.com>

Author: 3 people

integrations/premake.rst

@@ -6,13 +6,18 @@
 Conan provides different tools to help manage your projects using Premake. They can be
 imported from ``conan.tools.premake``. The most relevant tools are:
 
-- ``PremakeDeps``: the dependencies generator for Premake, to allow consuming dependencies from Premake projects
+- ``PremakeDeps``: the dependencies generator for Premake, to allow consuming dependencies from Premake projects.
+
+- ``PremakeToolchain``: the toolchain generator for Premake. It will create a
+  wrapper over premake scripts allowing premake workspace and projects
+  customization.
 
 - ``Premake``: the Premake build helper. It's simply a wrapper around the command line invocation of Premake.
 
 .. seealso::
 
     - Reference for :ref:`conan_tools_premake_premakedeps`.
+    - Reference for :ref:`conan_tools_premake_premaketoolchain`.
     - Reference for :ref:`conan_tools_premake_premake`.
 
 

reference/tools/premake.rst

@@ -6,5 +6,6 @@ conan.tools.premake
 .. toctree::
    :maxdepth: 2
 
-   premake/premake
    premake/premakedeps
+   premake/premaketoolchain
+   premake/premake

reference/tools/premake/premake.rst

@@ -7,7 +7,7 @@ Premake
 
 
 The ``Premake`` build helper is a wrapper around the command line invocation of Premake. It will abstract the
-project configuration command.
+project configuration and build command.
 
 The helper is intended to be used in the *conanfile.py* ``build()`` method, to call Premake commands automatically
 when a package is being built directly by Conan (create, install)
@@ -17,13 +17,12 @@ when a package is being built directly by Conan (create, install)
 .. code-block:: python
 
     from conan.tools.premake import Premake
-    from conan.tools.microsoft import MSBuild
 
     class Pkg(ConanFile):
         settings = "os", "compiler", "build_type", "arch"
 
-        # The VCVars generator might be needed in Windows-MSVC
-        generators = "VCVars"
+        # The PremakeToolchain generator is always needed to use premake helper
+        generators = "PremakeToolchain"
 
         def build(self):
             p = Premake(self)
@@ -36,16 +35,25 @@ when a package is being built directly by Conan (create, install)
 
             # Automatically determines the correct action:
             # - For MSVC, selects vs<version> based on the compiler version
-            # - Defaults to "gmake2" for other compilers
+            # - Defaults to "gmake" for other compilers
             # p.configure() will run: premake5 --file=myproject.lua <action> --{key}={value} ...
             p.configure()
-            # At the moment Premake does not contain .build() method
-            # report in Github issues your use cases and feedback to request it
-            build_type = str(self.settings.build_type)
-            if self.settings.os == "Windows":
-                msbuild = MSBuild(self)
-                msbuild.build("HelloWorld.sln")
-            else:
-                self.run(f"make config={build_type.lower()}_x86_64")
-            p = os.path.join(self.build_folder, "bin", build_type, "HelloWorld")
-            self.run(f'"{p}"')
+            # p.build() will invoke proper compiler depending on action (automatically detected by profile)
+            p.build("HelloWorld.sln")
+
+Reference
+---------
+
+.. currentmodule:: conan.tools.premake
+
+.. autoclass:: Premake
+    :members:
+
+conf
+----
+
+The ``Premake`` build helper is affected by these ``[conf]`` variables:
+
+- ``tools.build:verbosity`` which accepts one of ``quiet`` or ``verbose`` and sets the ``--quiet`` flag in ``Premake.configure()``
+
+- ``tools.compilation:verbosity`` which accepts one of ``quiet`` or ``verbose`` and sets the ``--verbose`` flag in ``Premake.build()``

reference/tools/premake/premakedeps.rst

@@ -6,8 +6,7 @@ PremakeDeps
 .. include:: ../../../common/experimental_warning.inc
 
 The ``PremakeDeps`` is the dependencies generator for Premake.
-
-The ``PremakeDeps`` generator can be used by name in conanfiles:
+The generator can be used by name in conanfiles:
 
 .. code-block:: python
     :caption: conanfile.py
@@ -34,23 +33,39 @@ And it can also be fully instantiated in the conanfile ``generate()`` method:
         requires = "zlib/1.2.11"
 
         def generate(self):
-            bz = PremakeDeps(self)
-            bz.generate()
-
-Generated files
----------------
+            deps = PremakeDeps(self)
+            deps.generate()
 
-When the ``PremakeDeps`` generator is used, every invocation of ``conan install`` will
-generate a ``include('conandeps.premake5.lua')`` that can be included and used in the project:
+.. important::
 
+    The ``PremakeDeps`` generator must be used in conjunction with the
+    :ref:`PremakeToolchain <conan_tools_premake_premaketoolchain>` generator, as it will
+    generate a ``include('conandeps.premake5.lua')`` that will be automatically
+    included by the toolchain.
 
-.. code-block:: lua
-
-    -- premake5.lua
-
-    include('conandeps.premake5.lua')
+Generated files
+---------------
 
-    workspace "HelloWorld"
-        conan_setup()
-        configurations { "Debug", "Release" }
-        platforms { "x86_64" }
+``PremakeDeps`` will generate a ``conandeps.premake5.lua`` script file which
+will be injected later by the toolchain and the following files per dependency in the ``conanfile.generators_folder``:
+
+- ``conan_<pkg>.premake5.lua``: will be including the proper script depending on the ``build_type`` and architecture.
+
+- ``conan_<pkg>_vars_<config>.premake5.lua``: will contain essentially the following information for the specific dependency, architecture and build_type:
+
+   - ``includedirs``
+   - ``libdirs``
+   - ``bindirs``
+   - ``sysincludedirs``
+   - ``frameworkdirs``
+   - ``frameworks``
+   - ``libs``
+   - ``syslibs``
+   - ``defines``
+   - ``cxxflags``
+   - ``cflags``
+   - ``sharedlinkflags``
+   - ``exelinkflags``
+
+All this information will be loaded in the ``conandeps.premake5.lua`` script
+and injected later to the main premake script, allowing a transparent and easy to use dependency management with conan.

reference/tools/premake/premaketoolchain.rst

@@ -0,0 +1,99 @@
+.. _conan_tools_premake_premaketoolchain:
+
+PremakeToolchain
+================
+
+.. include:: ../../../common/experimental_warning.inc
+
+.. important::
+
+    This class will generate files that are only compatible with Premake versions >= 5.0.0
+
+The ``PremakeToolchain`` generator can be used by name in conanfiles:
+
+.. code-block:: python
+    :caption: conanfile.py
+
+    class Pkg(ConanFile):
+        generators = "PremakeToolchain"
+
+
+.. code-block:: text
+    :caption: conanfile.txt
+
+    [generators]
+    PremakeToolchain
+
+And it can also be fully instantiated in the conanfile ``generate()`` method:
+
+**Usage Example:**
+
+.. code-block:: python
+
+    from conan.tools.premake import PremakeToolchain
+
+    class Pkg(ConanFile):
+        settings = "os", "compiler", "build_type", "arch"
+
+        def generate(self):
+            tc = PremakeToolchain(self)
+            tc.extra_defines = ["VALUE=2"]                      # Add define to main premake workspace
+            tc.extra_cflags = ["-Wextra"]                       # Add cflags to main premake workspace
+            tc.extra_cxxflags = ["-Wall", "-Wextra"]            # Add cxxflags to main premake workspace
+            tc.extra_ldflags = ["-lm"]                          # Add ldflags to main premake workspace
+            tc.project("main").extra_defines = ["TEST=False"]   # Add define to "main" project (overriding possible value)
+            tc.project("main").extra_cxxflags = ["-FS"]         # Add cxxflags to "main" project
+            tc.project("test").disable = True                   # A way of disabling "test" project compilation
+            tc.project("foo").kind = "StaticLib"                # Override library type of "foo"
+            tc.generate()
+
+Generated files
+---------------
+
+The ``PremakeToolchain`` generates ``conantoolchain.premake5.lua`` file after a :command:`conan install` (or when building the package
+in the cache) with the information provided in the ``generate()`` method as well as information
+translated from the current ``settings``, ``conf``, etc.
+
+Premake does not expose any kind of API to interact inject/modify the build scripts.
+Furthermore, premake does not have a concept of toolchain so following premake maintainers instructions, (see `premake discussion <https://github.com/premake/premake-core/discussions/2441>`_)
+as premake is built in top of Lua scripts, Conan generated file is a Lua script
+that will override the original premake script adding the following
+information:
+
+* Detection of ``buildtype`` from Conan settings.
+
+* Definition of the C++ standard as necessary.
+
+* Definition of the C standard as necessary.
+
+* Detection of the premake ``action`` based on conan profile and OS.
+
+* Definition of the build folder in order to avoid default premake behavior of
+  creating build folder and object files in the source repository (which goes
+  against conan good practices).
+
+* Definition of compiler and linker flags and defines based on user configuration values.
+
+* Definition of proper target architecture when cross building.
+
+* Definition of ``fPIC`` flag based on conan options.
+
+* Based on ``shared`` conan option, ``PremakeToolchain`` will set the ``kind`` of the ``workspace`` to ``SharedLib`` or ``StaticLib``.
+
+.. note::
+
+   ``PremakeToolchain`` is not able to override the ``kind`` of a project if that project has already define the ``kind`` attribute (typical case).
+   It can only override top-level ``workspace.kind``, which will only affect projects without a defined ``kind``.
+
+   **Recomendation**: as premake does not offer any mechanism like CMake's `BUILD_SHARED_LIBS <https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html#variable:BUILD_SHARED_LIBS>`_
+   to externally manage the creation type of libraries, it is recommended while
+   using conan to **AVOID** defining the ``kind`` attribute on library project. 
+
+
+Reference
+---------
+
+.. currentmodule:: conan.tools.premake
+
+.. autoclass:: PremakeToolchain
+    :members: