diff --git a/integrations/premake.rst b/integrations/premake.rst index 4992839b69d2..8d31e965f600 100644 --- a/integrations/premake.rst +++ b/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`. diff --git a/reference/tools/premake.rst b/reference/tools/premake.rst index 7357b6725865..861efa83f3f6 100644 --- a/reference/tools/premake.rst +++ b/reference/tools/premake.rst @@ -6,5 +6,6 @@ conan.tools.premake .. toctree:: :maxdepth: 2 - premake/premake premake/premakedeps + premake/premaketoolchain + premake/premake diff --git a/reference/tools/premake/premake.rst b/reference/tools/premake/premake.rst index 65685cc16bd3..53a0ee070ac2 100644 --- a/reference/tools/premake/premake.rst +++ b/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 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 --{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 ``Meson`` 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()`` diff --git a/reference/tools/premake/premakedeps.rst b/reference/tools/premake/premakedeps.rst index 14624f221b33..d19c02a8b128 100644 --- a/reference/tools/premake/premakedeps.rst +++ b/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 ` 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_.premake5.lua``: will be including the proper script depending on the ``build_type`` and architecture. + +- ``conan__vars_.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. diff --git a/reference/tools/premake/premaketoolchain.rst b/reference/tools/premake/premaketoolchain.rst new file mode 100644 index 000000000000..a7f8e55a90a4 --- /dev/null +++ b/reference/tools/premake/premaketoolchain.rst @@ -0,0 +1,87 @@ +.. _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 Premake + from conan.tools.microsoft import MSBuild + + 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 `_) +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. + + +Reference +--------- + +.. currentmodule:: conan.tools.premake + +.. autoclass:: PremakeToolchain + :members: