premake docs (#3925)

Author: memsharded

images/integrations/conan-premake-logo.png

@@ -22,13 +22,7 @@ Xcode.
    integrations/makefile
    integrations/xcode
    integrations/meson
+   integrations/premake
    integrations/android
    integrations/jfrog
    integrations/ros
-
-.. warning::
-
-    Even though there is a plugin for the Visual Studio IDE, it is not recommended to use
-    it right now because it has not been updated for the 2.0 version yet. However, we
-    intend to resume working on this plugin and enhance its functionality soon after Conan 2.0
-    is released.

integrations.rst

@@ -0,0 +1,19 @@
+.. _integrations_premake:
+
+|premake_logo| Premake
+======================
+
+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
+
+- ``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_premake`.
+
+
+.. |premake_logo| image:: ../images/integrations/conan-premake-logo.png

integrations/premake.rst

@@ -42,4 +42,5 @@ Contents:
     tools/ros
     tools/scm
     tools/scons
+    tools/premake
     tools/system

reference/tools.rst

@@ -0,0 +1,10 @@
+.. _conan_tools_premake:
+
+conan.tools.premake
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   premake/premake
+   premake/premakedeps

reference/tools/premake.rst

@@ -0,0 +1,39 @@
+.. _conan_tools_premake_premake:
+
+Premake
+=======
+
+.. include:: ../../../common/experimental_warning.inc
+
+
+The ``Premake`` build helper is a wrapper around the command line invocation of Premake. It will abstract the
+project configuration 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)
+
+
+.. 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"
+
+        def build(self):
+            p = Premake(self)
+            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}"')

reference/tools/premake/premake.rst

@@ -0,0 +1,56 @@
+.. _conan_tools_premake_premakedeps:
+
+PremakeDeps
+===========
+
+.. include:: ../../../common/experimental_warning.inc
+
+The ``PremakeDeps`` is the dependencies generator for Premake.
+
+The ``PremakeDeps`` generator can be used by name in conanfiles:
+
+.. code-block:: python
+    :caption: conanfile.py
+
+    class Pkg(ConanFile):
+        generators = "PremakeDeps"
+
+
+.. code-block:: text
+    :caption: conanfile.txt
+
+    [generators]
+    PremakeDeps
+
+And it can also be fully instantiated in the conanfile ``generate()`` method:
+
+.. code:: python
+
+    from conan import ConanFile
+    from conan.tools.premake import PremakeDeps
+
+    class App(ConanFile):
+        settings = "os", "arch", "compiler", "build_type"
+        requires = "zlib/1.2.11"
+
+        def generate(self):
+            bz = PremakeDeps(self)
+            bz.generate()
+
+Generated files
+---------------
+
+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:
+
+
+.. code-block:: lua
+
+    -- premake5.lua
+
+    include('conandeps.premake5.lua')
+
+    workspace "HelloWorld"
+        conan_setup()
+        configurations { "Debug", "Release" }
+        platforms { "x86_64" }