diff options
| -rw-r--r-- | doc/c/meson.build | 19 | ||||
| -rw-r--r-- | doc/deployment.rst | 47 | ||||
| -rw-r--r-- | doc/summary.rst | 21 |
3 files changed, 64 insertions, 23 deletions
diff --git a/doc/c/meson.build b/doc/c/meson.build index fc63421..761557d 100644 --- a/doc/c/meson.build +++ b/doc/c/meson.build @@ -10,8 +10,19 @@ conf_py = configure_file( output: 'conf.py', ) -configure_file(copy: true, input: '../deployment.rst', output: 'deployment.rst') -configure_file(copy: true, input: '../summary.rst', output: 'summary.rst') +deployment_rst = configure_file( + copy: true, + input: '../deployment.rst', + output: 'deployment.rst', +) + +summary_rst = configure_file( + copy: true, + input: '../summary.rst', + output: 'summary.rst', +) + +copied_rst_files = [deployment_rst, summary_rst] c_rst_files = files( 'index.rst', @@ -36,7 +47,7 @@ docs = custom_target( build_by_default: true, command: [sphinx_build, '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@', '-E', '-q', '-t', 'singlehtml'], - input: [c_rst_files, c_pugl_rst, c_index_xml], + input: [c_rst_files, copied_rst_files, c_pugl_rst, c_index_xml], install: true, install_dir: docdir / 'pugl-0', output: 'singlehtml', @@ -47,7 +58,7 @@ docs = custom_target( build_by_default: true, command: [sphinx_build, '-M', 'html', '@OUTDIR@', '@OUTDIR@', '-E', '-q', '-t', 'html'], - input: [c_rst_files, c_pugl_rst, c_index_xml], + input: [c_rst_files, copied_rst_files, c_pugl_rst, c_index_xml], install: true, install_dir: docdir / 'pugl-0', output: 'html', 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 <https://mesonbuild.com/Subprojects.html>`_ 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/ diff --git a/doc/summary.rst b/doc/summary.rst index e9cdc62..4f08c46 100644 --- a/doc/summary.rst +++ b/doc/summary.rst @@ -1,17 +1,16 @@ -Pugl is a library for writing portable and embeddable GUIs. -Pugl is not a toolkit or framework, -but a minimal portability layer that sets up a drawing context and delivers events. +Pugl is a minimal portability layer for embeddable GUIs. +It provides a drawing context and event-based main loop API, +which can be used to create graphical applications or embedded views. -Pugl is particularly suitable for use in plugins or other loadable modules. -It has no implicit context or mutable static data, -so it may be statically linked and used multiple times in the same process. - -Pugl has a modular design with a core library and separate graphics backends. -The core library implements platform support and depends only on standard system libraries. -MacOS, Windows, and X11 are currently supported as platforms. +Pugl is particularly suitable for plugins, +since it has no implicit context or mutable static data, +and can be statically linked. +The "core" library implements platform support, +and depends only on standard system libraries. +MacOS, Windows, and X11 are currently supported. Graphics backends are built as separate libraries, -so applications can depend only on the APIs that they use. +so applications depend only on the APIs that they use. Pugl includes graphics backends for Cairo_, OpenGL_, and Vulkan_. Other graphics APIs can be used by implementing a custom backend. |