From e493446eee14980e8747486300dabd02595b987a Mon Sep 17 00:00:00 2001 From: David Robillard Date: Tue, 23 May 2023 12:04:24 -0400 Subject: Improve introduction and deployment documentation --- doc/deployment.rst | 47 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 8 deletions(-) (limited to 'doc/deployment.rst') diff --git a/doc/deployment.rst b/doc/deployment.rst index 1e98e62..caa95a0 100644 --- a/doc/deployment.rst +++ b/doc/deployment.rst @@ -2,11 +2,12 @@ Usage ##### -********************* -Building Against Pugl -********************* +************************** +Using an Installed Version +************************** When Pugl is installed, +particularly on POSIX systems, pkg-config_ packages are provided that link with the core platform library and desired backend: .. code-block:: sh @@ -16,11 +17,41 @@ pkg-config_ packages are provided that link with the core platform library and d pkg-config --cflags --libs pugl-gl-0 pkg-config --cflags --libs pugl-vulkan-0 -Depending on one of these packages should be all that is necessary to use Pugl, -but details on the individual libraries that are installed are available in the README. +Depending on one of these packages should be all that is necessary to use Pugl. +If pkg-config is not available, +details on the individual libraries that are installed are available in the README. -If you are instead building directly from source, -all of the implementation files are in the ``src`` directory. -It is only necessary to build the platform and backend implementations that you need. +************************ +Using a Meson Subproject +************************ +Pugl uses the meson_ build system, +which allows it to be included as a subproject within other meson projects. + +To use Pugl as a subproject, +copy the source tree (or use a git submodule or subtree) to your ``subprojects`` directory, +for example to ``subprojects/pugl``, +and use the ``subproject`` function in meson to include it: + +.. code-block:: meson + + pugl_proj = subproject('pugl') + +See the `Meson subproject documentation `_ for details. + +****************** +Vendoring Manually +****************** + +To "vendor" Pugl with projects that use a different build system, +the headers in the ``include`` subdirectory and sources in ``src`` are needed. +The ``include`` directory needs to be added to the search path for the compiler, +and the required source files need to be compiled. +It is only necessary to build the needed platform and backend implementations. +Due to the modular design, +no centralized configuration is needed to enable or disable platform/backend support. +However, a few preprocessor symbols can be used to control which X11 features are used, +see the top of ``src/x11.c`` for details. + +.. _meson: https://mesonbuild.com/ .. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/ -- cgit v1.2.1