diff --git a/.editorconfig b/.editorconfig index 90edf178..92d03c09 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,3 +10,7 @@ insert_final_newline = true [Makefile] indent_style = tab indent_size = 8 + +[docs/sitemap.txt] +indent_style = tab +indent_size = 2 diff --git a/README.md b/README.md index c7e71239..a8ae0543 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,13 @@ # WirePlumber -WirePlumber is a session / policy manager implementation for -[PipeWire](https://pipewire.org). +WirePlumber is a modular session / policy manager for +[PipeWire](https://pipewire.org) and a GObject-based high-level library +that wraps PipeWire's API, providing convenience for writing the daemon's +modules as well as external tools for managing PipeWire. -# Compiling and Running +# Compiling & Running -## Dependencies +The most recent instructions can be found in the docs: -In order to compile WirePlumber you will need: - -* GLib >= 2.58 -* PipeWire 0.3 (master) - -At the moment, due to heavy development of both PipeWire and WirePlumber, -it is not always the case that the latest master of WirePlumber works with the -latest master of PipeWire. The safest PipeWire branch to use with WirePlumber -master is the `agl-next` branch from -[my personal clone](https://gitlab.freedesktop.org/gkiagia/pipewire) - -## Compilation - -WirePlumber uses the meson build system. For compatibility and ease of use, -though, a Makefile is also provided. The Makefile works only after the initial -configuration of the project with meson. - -Here is the very basic sequence of compiling for the first time: -``` -$ meson build -$ make -``` - -## Running automated tests - -WirePlumber has a few automated tests that you can easily run with: - -``` -$ make test -``` - -## Running - -1. First of all, you will need to run PipeWire. PipeWire itself comes with -an example session manager that you will need to disable in order to run -WirePlumber. This can be achieved by editing `src/daemon/pipewire.conf.in` -on the PipeWire git tree to disable the execution of the session manager: - -``` -diff --git a/src/daemon/pipewire.conf.in b/src/daemon/pipewire.conf.in -index bf64c574..e733e76c 100644 ---- a/src/daemon/pipewire.conf.in -+++ b/src/daemon/pipewire.conf.in -@@ -24,4 +24,4 @@ load-module libpipewire-module-access - load-module libpipewire-module-adapter - load-module libpipewire-module-link-factory - load-module libpipewire-module-session-manager --exec build/src/examples/media-session -+#exec build/src/examples/media-session -``` - -2. Second, you will need to run pipewire: in the **pipewire** source tree, do `make run` - -3. Without stopping pipewire, in the **wireplumber** source tree, do `make run` - -## Testing with an audio client - -The easiest way to test that things are working is to start a gstreamer pipeline -that outputs a test sound to pipewire. - -In the **pipewire** source tree, do: - -``` -$ make shell -$ gst-launch-1.0 audiotestsrc ! pwaudiosink -``` - -Note that `pwaudiosink` is currently only available in the `agl-next` branch. - -## Debugging - -The Makefile included with WirePlumber also supports the `gdb` and `valgrind` -targets. So, instead of `make run` you can do `make gdb` or `make valgrind` -to do some debugging. - -Getting debug messages on the command line is a matter of setting the -`G_MESSAGES_DEBUG` environment variable as documented in the GLib documentation. -Usually you can just do: - -``` -G_MESSAGES_DEBUG=all make run -``` - -Note that this only gives out WirePlumber's debug messages. If you want to also -see *libpipewire*'s debug messages, then you can also set: - -``` -PIPEWIRE_DEBUG=4 G_MESSAGES_DEBUG=all make run -``` - -... where `PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the -most verbose and 1 the least verbose. +* [Compilation](docs/index.md) +* [Running](docs/daemon.md) diff --git a/docs/configuration.md b/docs/configuration.md index 4be1824c..98641fff 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,4 +1,4 @@ -# WirePlumber Configuration +# Configuration WirePlumber is a heavily modular daemon. By itself, it doesn't do anything except load the configured modules. All the rest of the logic is implemented diff --git a/docs/daemon.md b/docs/daemon.md new file mode 100644 index 00000000..54145f21 --- /dev/null +++ b/docs/daemon.md @@ -0,0 +1,65 @@ +# Daemon + +The WirePlumber daemon implements the session & policy management service. + +## Running + +1. First of all, you will need to run PipeWire. PipeWire itself comes with +an example session manager that you will need to disable in order to run +WirePlumber. This can be achieved by editing `src/daemon/pipewire.conf.in` +on the PipeWire git tree to disable the execution of the session manager: + +``` +diff --git a/src/daemon/pipewire.conf.in b/src/daemon/pipewire.conf.in +index bf64c574..e733e76c 100644 +--- a/src/daemon/pipewire.conf.in ++++ b/src/daemon/pipewire.conf.in +@@ -24,4 +24,4 @@ load-module libpipewire-module-access + load-module libpipewire-module-adapter + load-module libpipewire-module-link-factory + load-module libpipewire-module-session-manager +-exec build/src/examples/media-session ++#exec build/src/examples/media-session +``` + +2. Second, you will need to run pipewire: in the **pipewire** source tree, do `make run` + +3. Without stopping pipewire, in the **wireplumber** source tree, do `make run` + +## Testing with an audio client + +The easiest way to test that things are working is to start a gstreamer pipeline +that outputs a test sound to pipewire. + +In the **pipewire** source tree, do: + +``` +$ make shell +$ gst-launch-1.0 audiotestsrc ! pwaudiosink +``` + +Note that `pwaudiosink` is currently only available in the `agl-next` branch. + +## Debugging + +The Makefile included with WirePlumber also supports the `gdb` and `valgrind` +targets. So, instead of `make run` you can do `make gdb` or `make valgrind` +to do some debugging. + +Getting debug messages on the command line is a matter of setting the +`G_MESSAGES_DEBUG` environment variable as documented in the GLib documentation. +Usually you can just do: + +``` +G_MESSAGES_DEBUG=all make run +``` + +Note that this only gives out WirePlumber's debug messages. If you want to also +see *libpipewire*'s debug messages, then you can also set: + +``` +PIPEWIRE_DEBUG=4 G_MESSAGES_DEBUG=all make run +``` + +... where `PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the +most verbose and 1 the least verbose. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..924db3a4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,41 @@ +# WirePlumber + +WirePlumber is a modular session / policy manager for +[PipeWire](https://pipewire.org) and a GObject-based high-level library +that wraps PipeWire's API, providing convenience for writing the daemon's +modules as well as external tools for managing PipeWire. + +## Compiling + +### Dependencies + +In order to compile WirePlumber you will need: + +* GLib >= 2.58 +* PipeWire 0.3 (master) + +At the moment, due to heavy development of both PipeWire and WirePlumber, +it is not always the case that the latest master of WirePlumber works with the +latest master of PipeWire. The safest PipeWire branch to use with WirePlumber +master is the `agl-next` branch from +[my personal clone](https://gitlab.freedesktop.org/gkiagia/pipewire) + +### Compilation + +WirePlumber uses the meson build system. For compatibility and ease of use, +though, a Makefile is also provided. The Makefile works only after the initial +configuration of the project with meson. + +Here is the very basic sequence of compiling for the first time: +``` +$ meson build +$ make +``` + +### Running automated tests + +WirePlumber has a few automated tests that you can easily run with: + +``` +$ make test +``` diff --git a/docs/library.md b/docs/library.md new file mode 100644 index 00000000..3675a43a --- /dev/null +++ b/docs/library.md @@ -0,0 +1 @@ +# Library API diff --git a/docs/meson.build b/docs/meson.build new file mode 100644 index 00000000..028d111d --- /dev/null +++ b/docs/meson.build @@ -0,0 +1,42 @@ +hotdoc_p = find_program('hotdoc', required: get_option('doc')) +if not hotdoc_p.found() + message('Hotdoc not found, not building the documentation') + subdir_done() +endif + +hotdoc = import('hotdoc') +required_hotdoc_extensions = ['gi-extension'] +foreach extension: required_hotdoc_extensions + if not hotdoc.has_extensions(extension) + if get_option('doc').enabled() + error('Documentation enabled but @0@ missing'.format(extension)) + endif + + message('@0@ extension not found, not building documentation'.format(extension)) + subdir_done() + endif +endforeach + +if not build_gir + if get_option('doc').enabled() + error('Documentation enabled but introspection not built.') + endif + + message('Introspection not built, can\'t build the documentation') + subdir_done() +endif + +wp_doc = hotdoc.generate_doc('wireplumber', + project_version: wireplumber_api_version, + sitemap: 'sitemap.txt', + index: 'index.md', + gi_index: 'library.md', + gi_smart_index: true, + gi_sources: [wp_gir[0].full_path()], + gi_c_sources: [wp_lib_sources, wp_lib_headers, wpenums_c, wpenums_h], + gi_c_source_roots: [join_paths(meson.current_source_dir(), '../lib/wp/'), ], + languages: ['c'], + dependencies: [wp_dep], + build_by_default: true, + install: true, +) diff --git a/docs/sitemap.txt b/docs/sitemap.txt new file mode 100644 index 00000000..c1dc372f --- /dev/null +++ b/docs/sitemap.txt @@ -0,0 +1,4 @@ +index.md + gi-index + daemon.md + configuration.md diff --git a/lib/wp/meson.build b/lib/wp/meson.build index f399237d..7f07c262 100644 --- a/lib/wp/meson.build +++ b/lib/wp/meson.build @@ -1,4 +1,4 @@ -wp_lib_sources = [ +wp_lib_sources = files( 'base-endpoint.c', 'configuration.c', 'core.c', @@ -19,9 +19,9 @@ wp_lib_sources = [ 'proxy-port.c', 'session.c', 'spa-props.c', -] +) -wp_lib_headers = [ +wp_lib_headers = files( 'base-endpoint.h', 'configuration.h', 'core.h', @@ -43,7 +43,7 @@ wp_lib_headers = [ 'proxy-link.h', 'session.h', 'wp.h', -] +) install_headers(wp_lib_headers, subdir : join_paths('wireplumber-' + wireplumber_api_version, 'wp') @@ -56,9 +56,12 @@ enums = gnome.mkenums_simple('wpenums', install_header: true, install_dir: join_paths(get_option('includedir'), 'wireplumber-' + wireplumber_api_version, 'wp'), ) +wpenums_h = enums[1] +wpenums_c = enums[0] +wp_gen_sources = [wpenums_h] wp_lib = library('wireplumber-' + wireplumber_api_version, - wp_lib_sources, enums, + wp_lib_sources, wpenums_c, wpenums_h, c_args : [ '-D_GNU_SOURCE', '-DG_LOG_USE_STRUCTURED', @@ -73,21 +76,22 @@ wp_lib = library('wireplumber-' + wireplumber_api_version, version: meson.project_version(), ) -if get_option('introspection') - gnome.generate_gir(wp_lib, +if build_gir + wp_gir = gnome.generate_gir(wp_lib, namespace: 'Wp', nsversion: wireplumber_api_version, - sources: [wp_lib_sources, wp_lib_headers, enums], + sources: [wp_lib_sources, wp_lib_headers, wpenums_c, wpenums_h], includes: ['GLib-2.0', 'GObject-2.0', 'Gio-2.0'], install: true, ) + wp_gen_sources += wp_gir endif wp_dep = declare_dependency( link_with: wp_lib, - sources: enums[1], + sources: wp_gen_sources, include_directories: wp_lib_include_dir, - dependencies: [gobject_dep] + dependencies: [gobject_dep, gio_dep] ) pkgconfig.generate(wp_lib, diff --git a/meson.build b/meson.build index ca0c6c08..2ff163ac 100644 --- a/meson.build +++ b/meson.build @@ -1,7 +1,7 @@ project('wireplumber', ['c', 'cpp'], version : '0.1.90', license : 'MIT', - meson_version : '>= 0.47.0', + meson_version : '>= 0.51.0', default_options : [ 'warning_level=1', 'buildtype=debugoptimized', @@ -35,6 +35,8 @@ pipewire_dep = dependency('libpipewire-0.3') gnome = import('gnome') pkgconfig = import('pkgconfig') +gir = find_program('g-ir-scanner', required : get_option('introspection')) +build_gir = gir.found() wp_lib_include_dir = include_directories('lib') @@ -49,6 +51,7 @@ if ccpp.has_argument('-fvisibility=hidden') endif subdir('lib') +subdir('docs') subdir('modules') subdir('src') subdir('tests') diff --git a/meson_options.txt b/meson_options.txt index 7cec6c3a..7af3bef4 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -1 +1,4 @@ -option('introspection', type : 'boolean', value : true) +option('introspection', type : 'feature', value : 'auto', + description : 'Generate gobject-introspection bindings') +option('doc', type : 'feature', value : 'auto', + description: 'Enable documentation.')