Merge branch 'develop2' into release/2.17

Author: czoido

examples/cross_build.rst

@@ -9,5 +9,6 @@ Cross-building examples
    cross_build/toolchain_packages
    cross_build/android/ndk
    cross_build/android/android_studio
+   cross_build/emscripten
    cross_build/tricore
    cross_build/linux_to_windows_mingw

examples/cross_build/emscripten.rst

@@ -0,0 +1,139 @@
+.. _examples_cross_build_emscripten:
+
+Cross-building with Emscripten - WebAssembly and asm.js
+=======================================================
+
+This example demonstrates how to cross-build a simple C++ project using Emscripten and Conan.
+
+Conan supports `WASM <https://webassembly.org>`_ cross compilation, giving you the flexibility to target different
+JavaScript/WebAssembly runtimes in the browser.
+
+We recommend creating separate Conan profiles for each target. Below are
+recommended profiles and instructions on how to build with them.
+
+
+Setting up Conan profile for WebAssembly (WASM)
+-----------------------------------------------
+
+.. code-block:: text
+
+   [settings]
+   arch=wasm
+   build_type=Release
+   compiler=emcc
+   compiler.cppstd=17
+   compiler.libcxx=libc++
+   # Optional settings to enable multithreading (see note below)
+   # compiler.threads=posix
+   compiler.version=4.0.10
+   os=Emscripten
+
+   [tool_requires]
+   emsdk/4.0.10
+
+   [conf]
+   # Optional settings to enable memory allocation
+   tools.build:exelinkflags=['-sALLOW_MEMORY_GROWTH=1', '-sMAXIMUM_MEMORY=4GB', '-sINITIAL_MEMORY=64MB']
+   tools.build:sharedlinkflags=['-sALLOW_MEMORY_GROWTH=1', '-sMAXIMUM_MEMORY=4GB', '-sINITIAL_MEMORY=64MB']
+
+
+.. note::
+    
+    Conan also supports building for `asm.js <http://asmjs.org>`_ targets, which is a nowadays considered deprecated.
+
+    What’s the difference between asm.js and WASM?
+
+    - **asm.js** is a subset of JavaScript optimized for speed. It is fully supported by all browsers (even older ones) and compiles to a large ``.js`` file.
+    - **WebAssembly (WASM)** is a binary format that is smaller and faster to load and execute. Most modern browsers support it, and it is generally recommended for new projects. **WASM** is also easier to integrate with native browser APIs compared to **asm.js**.
+
+
+Even though Emscripten is not a true runtime environment (like Linux or
+Windows), it is part of a toolchain ecosystem that compiles C/C++ to
+WebAssembly (WASM) and asm.js.
+
+Conan uses ``os=Emscripten`` to:
+
+- Align with the toolchain: Emscripten integrates the compiler, runtime glue, and JavaScript environment, making it practical to treat as an "OS-like" target.
+
+- Support backward compatibility: Many recipes in Conan Center Index use ``os=Emscripten`` to enable or disable features and dependencies that specifically target Emscripten.
+
+- Maintain stability: Changing this setting would break recipes that rely on it, and would complicate compatibility with alternative WASM toolchains.
+
+
+.. note::
+
+   ``wasm`` arch refers to ``WASM 32-bit`` target architecture, which is the
+   default. If you wish to target ``WASM64``, set ``arch=wasm64`` in your profile.
+   **Note that WASM64 is still experimental** and requires Node.js v20+ and a browser that supports it.
+
+.. important::
+
+    According to `emscripten documentation <https://emscripten.org/docs/api_reference/wasm_workers.html>`_ Emscripten supports two multithreading APIs:
+
+    - POSIX Threads API (``posix`` in conan profile)
+    - Wasm Workers API (``wasm_workers`` in conan profile)
+
+    These two APIs are incompatible with each other and incompatibles with binaries compiled without threading support.
+    This incompatibility necessitates the modeling of threading usage within
+    the compiler's binary model, allowing conan to distinguish between binaries
+    compiled with threading and those compiled without it.
+
+    Conan will automatically set compiler and linker flags to enable threading if configured in the profile.
+
+
+The profiles above use the ``emsdk`` package from `Conan Center Index repository <https://conan.io/center/recipes/emsdk>`_, which provides the Emscripten SDK, including ``emcc``, ``em++``, and tools like ``emrun`` and ``node``.
+
+If you prefer to use your system-installed Emscripten instead of the Conan-provided one, ``tool_requires`` could be replaced by custom ``compiler_executables`` and ``buildenv``:
+
+.. code-block:: text
+
+  [conf]
+  tools.build:compiler_executables={'c':'/path/to/emcc', 'cpp':'/path/to/em++'}
+
+  [buildenv]
+  CC=emcc
+  CXX=em++
+  AR=emar
+  NM=emnm
+  RANLIB=emranlib
+  STRIP=emstrip
+
+
+This way conan could configure `emsdk` local installation to be used from `CMake`, `Meson`, `Autotools` or other build systems.
+
+In some cases, you might also need the ``Emscripten.cmake`` toolchain file
+for advanced scenarios. This toolchais is already added in our packaged
+`emsdk` but if you are using your own Emscripten installation, you can
+specify it in the profile by using
+:ref:`tools.cmake.cmaketoolchain:user_toolchain<conan_cmake_user_toolchain>`
+and providing the absolute path to your toolchain file.
+
+.. note::
+
+   The ``tools.build:exelinkflags`` and ``tools.build:sharedlinkflags`` in
+   previous profiles are recomendations but users can modify them or define
+   their values in the CMakeLists.txt file using the
+   ``set_target_properties()`` command.
+
+   - By enabling ``ALLOW_MEMORY_GROWTH`` we allow the runtime to grow its
+     memory dynamically at runtime by calling ``emscripten_resize_heap()``. Without
+     this flag, memory is allocated at startup and cannot grow.
+
+   - The ``MAXIMUM_MEMORY`` and ``INITIAL_MEMORY`` values specifies the maximum
+     and initial memory size for the Emscripten runtime. These values can be
+     adjusted based on your application's needs. 
+
+     Take into account that ``arch=wasm64`` has a theorical exabytes maximum
+     memory size, but runtime currently limits it to 16GB, while ``arch=wasm32``
+     has a maximum memory size of 4GB and ``arch=asm.js`` has a maximum memory size of 2GB.
+    
+
+.. important::
+
+   ``emcc`` compiler does not guarantee any ABI compatibility between different versions (patches included)
+   To ensure a new ``package_id`` is generated when the Emscripten version
+   changes, it is recommended to update the ``compiler.version`` setting in your profile accordingly.
+
+   This will ensure that the package ID is generated based on the Emscripten
+   version, allowing Conan to detect changes in the Emscripten toolchain and
+   rebuild the project accordingly.

images/conan-report-diff_html.png

@@ -46,10 +46,20 @@ The new fields that can be defined in the ``cpp_info`` or ``cpp_info.components`
    self.cpp_info.languages # same as "languages" attribute, it can be "C", "C++"
    self.cpp_info.exe  # Definition of an executable artifact
    self.cpp_info.package_framework  # Definition of an Apple Framework (new since Conan 2.14)
+   self.cpp_info.sources  # List of paths to source files in the package (for packages that provide source code to consumers)
 
 
 These fields will be auto-deduced from the other ``cpp_info`` and ``components`` definitions, like the ``libs`` or ``libdirs`` fields, but the automatic deduction might have limitations. Defining them explicitly will inhibit the auto deduction and use the value as provided by the recipe.
 
+Declare sources for targets with:
+
+.. code-block:: python
+
+   self.cpp_info.sources = ["src/mylib.cpp", "src/other.cpp"]
+
+This allows packages to provide source code as a dependency to consumers. The paths should be relative to the package folder.
+The source files will be added as `INTERFACE_SOURCES` property to the CMake library (or component) target and consumers that
+link with this target will compile the sources when building their own targets.
 
 This feature is enabled with the ``-c tools.cmake.cmakedeps:new=will_break_next`` configuration. The value ``will_break_next`` will change in next releases to emphasize the fact that this feature is not suitable for usage beyond testing. Just by enabling this conf and forcing the build of packages that use ``CMakeDeps`` will trigger the usage of the new generator.
 

images/integrations/conan-emscripten-logo.png

@@ -22,6 +22,7 @@ Xcode.
    integrations/makefile
    integrations/xcode
    integrations/meson
+   integrations/emscripten
    integrations/premake
    integrations/android
    integrations/jfrog

incubating.rst

@@ -0,0 +1,14 @@
+.. _integrations_emscripten:
+
+|emscripten_logo| Emscripten
+============================
+
+Conan provides support for cross-building for both `asm.js <http://asmjs.org>`_ and `WASM <https://webassembly.org>`_ (Web Assembly) targets
+using `Emscripten <https://emscripten.org>`__. This enables developers to compile C/C++ code for the browser
+and other JavaScript environments.
+
+For detailed examples and step-by-step instructions, refer to:
+
+- :ref:`Cross-building with Emscripten <examples_cross_build_emscripten>`
+
+.. |emscripten_logo| image:: ../images/integrations/conan-emscripten-logo.png

integrations.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`.
 
 

integrations/emscripten.rst

@@ -16,7 +16,6 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
    :maxdepth: 1
    :hidden:
 
-   commands/audit
    commands/cache
    commands/config
    commands/graph
@@ -32,7 +31,6 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
    commands/version
    commands/workspace
 
-- :doc:`conan audit <commands/audit>`: Check for vulnerabilities in your Conan packages
 - :doc:`conan cache <commands/cache>`: Return the path of recipes and packages in the cache
 - :doc:`conan config <commands/config>`: Manage Conan configuration (remotes, settings, plugins, etc)
 - :doc:`conan graph <commands/graph>`: Obtain information about the dependency graph without fetching binaries
@@ -78,6 +76,18 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
 - :doc:`conan test <commands/test>`: Test a package
 - :doc:`conan upload <commands/upload>`: Upload packages from the local cache to a specified remote
 
+**Security Commands**
+
+.. toctree::
+   :caption: Security Commands
+   :maxdepth: 1
+   :hidden:
+
+   commands/audit
+   commands/report
+
+- :doc:`conan audit <commands/audit>`: Checks for vulnerabilities in your Conan packages.
+- :doc:`conan report <commands/report>`: Get information about the packages
 
 .. _commands_output:
 

integrations/premake.rst

@@ -13,25 +13,26 @@ See :ref:`the audit devops page<devops_audit>` to see examples on how to use the
 
 
 conan audit scan
-================
+^^^^^^^^^^^^^^^^
 
 .. autocommand::
     :command: conan audit scan -h
 
-The ``conan audit scan`` checks for vulnerabilities in the given references and their transitive dependencies.
+The ``conan audit scan`` command checks for vulnerabilities in the given references and their transitive dependencies.
 This command receives configuration arguments such as profiles and settings, to control the expansion of the graph.
 
 conan audit list
-================
+^^^^^^^^^^^^^^^^
 
 .. autocommand::
     :command: conan audit list -h
 
 The ``conan audit list`` command lists vulnerabilities for the given references, without checking their transitive dependencies.
-You can pass a single reference, or a pkglist file with multiple references.
+You can pass a single reference, a pkglist file with multiple references,
+a cyclonedx SBOM file generated with the :ref:`conan.tools.sbom <conan_tools_sbom>` module, or a Conan lockfile.
 
 conan audit provider
-====================
+^^^^^^^^^^^^^^^^^^^^
 
 .. autocommand::
     :command: conan audit provider -h
@@ -42,6 +43,7 @@ By default the ``conan audit`` subcommands use the ConanCenter provider, but you
 For now, besides the default ConanCenter provider, only private JFrog Security providers are supported, see :ref:`the audit devops page<devops_audit_private_providers>` for more information.
 
 There are 3 subcommands:
+
 - ``conan audit provider auth``: Authenticates a provider with a token.
 - ``conan audit provider add``: Adds a provider to the list.
 - ``conan audit provider remove``: Removes a provider from the list.