diff options
Diffstat (limited to 'docs')
35 files changed, 627 insertions, 207 deletions
diff --git a/docs/markdown/Continuous-Integration.md b/docs/markdown/Continuous-Integration.md index f24bdb0..ec0b4e0 100644 --- a/docs/markdown/Continuous-Integration.md +++ b/docs/markdown/Continuous-Integration.md @@ -207,7 +207,7 @@ GCC on Linux, Mac and Windows. The optional `on:` parameters only run this CI when the C code is changed--corresponding ci_python.yml might run only on "**.py" file changes. -```yml +```yaml name: ci_meson on: diff --git a/docs/markdown/Getting-meson.md b/docs/markdown/Getting-meson.md index ec6f1c6..c3c3cc8 100644 --- a/docs/markdown/Getting-meson.md +++ b/docs/markdown/Getting-meson.md @@ -1,6 +1,6 @@ # Getting Meson -Meson is implemented in Python 3, and requires 3.6 or newer. If your +Meson is implemented in Python 3, and requires 3.7 or newer. If your operating system provides a package manager, you should install it with that. For platforms that don't have a package manager, you need to download it from [Python's home page]. See below for @@ -14,7 +14,7 @@ itself without doing anything special. On Windows, if you did not install Python with the installer options that make Python scripts executable, you will have to run `python -/path/to/meson.py`, where `python` is Python 3.6 or newer. +/path/to/meson.py`, where `python` is Python 3.7 or newer. The newest development code can be obtained directly from [Git], and we strive to ensure that it will always be working and usable. All diff --git a/docs/markdown/Getting-meson_ptbr.md b/docs/markdown/Getting-meson_ptbr.md index b5af345..f4f3ac1 100644 --- a/docs/markdown/Getting-meson_ptbr.md +++ b/docs/markdown/Getting-meson_ptbr.md @@ -1,6 +1,6 @@ # Obtendo o Meson -Meson é implementado em Python 3, e requer a versão 3.6 ou mais nova. +Meson é implementado em Python 3, e requer a versão 3.7 ou mais nova. se o seu sistema operacional provê um gerenciador de pacotes, você deve instalar o Meson com ele. Para plataformas que não tem um gerenciador de pacotes, você precisa baixa-lo da [página inicial do Python]. Veja abaixo @@ -14,7 +14,7 @@ do git sem fazer nada de especial. No Windows, se você não instalar o Python com a opção do instalador que fazem os *scripts* Python executáveis, você vai ter que executar `python -/path/to/meson.py`, onde `python` é o Python 3.6 ou mais novo. +/path/to/meson.py`, onde `python` é o Python 3.7 ou mais novo. O código de desenvolvimento mais recente pode ser obtido diretamente do [Git], e nós lutamos para garatir que ele vai estar sempre funcionando e usável. Todos diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md index 4f08c6d..616562a 100644 --- a/docs/markdown/Gnome-module.md +++ b/docs/markdown/Gnome-module.md @@ -133,8 +133,7 @@ argument is the basename of the output files. * `nostdinc`: if true, don't include the standard marshallers from glib * `prefix`: the prefix to use for symbols * `skip_source`: if true, skip source location comments -* `sources` []str *required*: List of string sources to consume -* `sources`: the list of sources to use as inputs +* `sources` [](str | File) *required*: the list of sources to use as inputs * `stdinc`: if true, include the standard marshallers from glib * `valist_marshallers`: if true, generate va_list marshallers @@ -321,8 +320,8 @@ VAPI or Vala binaries. languages: []string, symlink_media: bool = true): void ``` -Installs help documentation using Yelp. The first argument is the -project id. +Installs help documentation for Yelp using itstool and gettext. The first +argument is the project id. Additionally, sources can be passed as additional positional arguments. This was, however, undocumented and never officially supported. Due to a longstanding diff --git a/docs/markdown/RPM-module.md b/docs/markdown/RPM-module.md deleted file mode 100644 index cab6d96..0000000 --- a/docs/markdown/RPM-module.md +++ /dev/null @@ -1,16 +0,0 @@ -# RPM module - -The RPM module can be used to create a sample rpm spec file for a -Meson project. It autodetects installed files, dependencies and so -on. Using it is very simple. At the very end of your Meson project -(that is, the end of your top level `meson.build` file) add these two -lines. - -```meson -rpm = import('rpm') -rpm.generate_spec_template() -``` - -Run Meson once on your code and the template will be written in your -build directory. Then remove the two lines above and manually edit the -template to add missing information. After this it is ready for use. diff --git a/docs/markdown/Release-notes-for-0.61.0.md b/docs/markdown/Release-notes-for-0.61.0.md new file mode 100644 index 0000000..8798453 --- /dev/null +++ b/docs/markdown/Release-notes-for-0.61.0.md @@ -0,0 +1,138 @@ +--- +title: Release 0.61.0 +short-description: Release notes for 0.61.0 +... + +# New features + +## backend_startup_project + +`backend_startup_project` will no longer erase the last project in a VS +solution if it is not the specified project. + +## Windows.compile_resources CustomTarget + +Previously the Windows module only accepted CustomTargets with one output, it +now accepts them with more than one output, and creates a windows resource +target for each output. Additionally it now accepts indexes of CustomTargets + +```meson + +ct = custom_target( + 'multiple', + output : ['resource', 'another resource'], + ... +) + +ct2 = custom_target( + 'slice', + output : ['resource', 'not a resource'], + ... +) + +resources = windows.compile_resources(ct, ct2[0]) +``` + +## Add a man page backend to refman + +The refman docs (function and object reference) can now be generated as a man +page. + +## ``extract_objects()`` supports generated sources + +Custom targets or generated files (returned by ``generator.process()``) +can now be passed to ``extract_objects()``. + +## Python 3.6 support will be dropped in the next release + +The final [Python 3.6 release was 3.6.15 in September](https://www.python.org/dev/peps/pep-0494/#lifespan). +This release series is now End-of-Life (EOL). The only LTS distribution that +still ships Python 3.5 as the default Python is Ubuntu 18.04, which has Python +3.8 available as well. + +Python 3.7 has various features that we find useful such as future annotations, +the importlib.resources module, and dataclasses. + +As a result, we will begin requiring Python 3.7 or newer in Meson 0.62, which +is the next release. Starting with Meson 0.61, we now print a `NOTICE:` when +a `meson` command is run on Python 3.6 to inform users about this. + +## Warning if check kwarg of run_command is missing + +The `check` kwarg of `run_command` currently defaults to `false`. +Because we want to change that, running +```meson +run_command('cmd') +``` +now results in: +```text +WARNING: You should add the boolean check kwarg to the run_command call. + It currently defaults to false, + but it will default to true in future releases of meson. + See also: https://github.com/mesonbuild/meson/issues/9300 +``` + +## `meson rewrite` can modify `extra_files` + +The build script rewriter can now modify targets' `extra_files` lists, +or create them if absent. It it used in the same way as with rewriting +source lists: + +```bash +meson rewrite target <target name/id> {add_extra_files/rm_extra_files} [list of extra files] +``` + +The rewriter's script mode also supports these actions: + +```json +{ + "type": "target", + "target": "<target name>", + "operation": "extra_files_add / extra_files_rm", + "sources": ["list", "of", "extra", "files", "to", "add, remove"], +} +``` + +## `meson rewrite target <target> info` outputs *target*'s `extra_files` + +Targets' `extra_files` lists are now included in the rewriter's target info dump +as a list of file paths, in the same way `sources` are. This applies to both +`meson rewrite` CLI and script mode. + +## Visual Studio 2022 backend + +As Visual Studio 2022 is released recently, it's time to support the +new version in Meson. This mainly includes the new "v143" platform tools. + +The usage is similar to other backends. For example +```meson +meson setup builddir --backend=vs2022 +``` +will configure "builddir" for projects compatible with Visual Studio 2022. + +## Support for CMake <3.14 is now deprecated for CMake subprojects + +In CMake 3.14, the File API was introduced and the old CMake server API was +deprecated (and removed in CMake 3.20). Thus support for this API will also +be removed from Meson in future releases. + +This deprecation only affects CMake subprojects. + +## Added support for sccache + +Meson now supports [sccache](https://github.com/mozilla/sccache) just +like it has supported CCache. If both sccache and CCache are +available, the autodetection logic prefers sccache. + +## install_symlink function + +It is now possible to request for symbolic links to be installed during +installation. The `install_symlink` function takes a positional argument to +the link name, and installs a symbolic link pointing to `pointing_to` target. +The link will be created under `install_dir` directory and cannot contain path +separators. + +```meson +install_symlink('target', pointing_to: '../bin/target', install_dir: '/usr/sbin') +``` + diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index 2873cbc..2bc0b9b 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -31,7 +31,7 @@ meson setup builddir We invoke Meson with the `setup` command, giving it the location of the build directory. Meson uses [out of source -builds](http://voices.canonical.com/jussi.pakkanen/2013/04/16/why-you-should-consider-using-separate-build-directories/). +builds](http://web.archive.org/web/20190715081007/http://voices.canonical.com/jussi.pakkanen/2013/04/16/why-you-should-consider-using-separate-build-directories/). Hint: The syntax of Meson is `meson [command] [arguments] [options]`. The `setup` command takes a `builddir` and a `srcdir` argument. If no diff --git a/docs/markdown/Rust-module.md b/docs/markdown/Rust-module.md index 9f8b09b..54834b7 100644 --- a/docs/markdown/Rust-module.md +++ b/docs/markdown/Rust-module.md @@ -34,7 +34,7 @@ that automatically. Additional, test only dependencies may be passed via the dependencies argument. -### bindgen(*, input: string | BuildTarget | []string | []BuildTarget, output: string, include_directories: []include_directories, c_args: []string, args: []string) +### bindgen(*, input: string | BuildTarget | [](string | BuildTarget), output: string, include_directories: []include_directories, c_args: []string, args: []string) This function wraps bindgen to simplify creating rust bindings around C libraries. This has two advantages over hand-rolling ones own with a @@ -60,8 +60,8 @@ rust = import('unstable-rust') inc = include_directories('..'¸ '../../foo') generated = rust.bindgen( - 'myheader.h', - 'generated.rs', + input : 'myheader.h', + output : 'generated.rs', include_directories : [inc, include_directories('foo')], args : ['--no-rustfmt-bindings'], c_args : ['-DFOO=1'], @@ -77,7 +77,7 @@ h1 = custom_target(...) h2 = custom_target(...) r1 = rust.bindgen( - [h1, h2], # h1 includes h2, - 'out.rs', + input : [h1, h2], # h1 includes h2, + output : 'out.rs', ) ``` diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md index 7cb04e0..fef9d11 100644 --- a/docs/markdown/Subprojects.md +++ b/docs/markdown/Subprojects.md @@ -153,7 +153,7 @@ Because this is such a common operation, Meson provides a shortcut for this use case. ```meson -dep = dependency('foo', fallback : [subproject_name, variable_name]) +dep = dependency('foo', fallback : ['subproject_name', 'variable_name']) ``` The `fallback` keyword argument takes two items, the name of the diff --git a/docs/markdown/Users.md b/docs/markdown/Users.md index bd146d7..8510d6e 100644 --- a/docs/markdown/Users.md +++ b/docs/markdown/Users.md @@ -94,7 +94,7 @@ format files - [Libvirt](https://libvirt.org), a toolkit to manage virtualization platforms - [Libzim](https://github.com/openzim/libzim), the reference implementation for the ZIM file format - [Marker](https://github.com/fabiocolacio/Marker), a GTK-3 markdown editor - - [Mesa](https://gitlab.freedesktop.org/mesa/mesa/), an open source graphics driver project + - [Mesa](https://mesa3d.org/), an open source graphics driver project - [MiracleCast](https://github.com/albfan/miraclecast), connect external monitors to your system via Wifi-Display specification aka Miracast - [mpv](https://github.com/mpv-player/mpv), a free, open source, and cross-platform media player - [mrsh](https://github.com/emersion/mrsh), a minimal POSIX shell diff --git a/docs/markdown/fallback-wraptool.md b/docs/markdown/fallback-wraptool.md deleted file mode 100644 index d4f5af2..0000000 --- a/docs/markdown/fallback-wraptool.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: fallback wraptool -... - -# In case of emergency - -In case wraptool is down we have created a backup script that you can -use to download wraps directly from the GitHub repos. It is not as -slick and may have bugs but at least it will allow you to use wraps. - -## Using it - -To list all available wraps: - - ghwt.py list - -To install a wrap, go to your source root, make sure that the -`subprojects` directory exists and run this command: - - ghwt.py install <projectname> [<branchname>] - -This will stage the subproject ready to use. If you have multiple -subprojects you need to download them all manually. - -Specifying branch name is optional. If not specified, the list of -potential branches is sorted alphabetically and the last branch is -used. - -*Note* The tool was added in 0.32.0, for versions older than that you -need to delete the `foo.wrap` file to work around this issue. - -## How to upgrade an existing dir/fix broken state/any other problem - -Nuke the contents of `subprojects` and start again. - -## Known issues - -Some repositories show up in the list but are not installable. They -would not show up in the real WrapDB because they are works in -progress. - -GitHub web API limits the amount of queries you can do to 60/hour. If -you exceed that you need to wait for the timer to reset. diff --git a/docs/markdown/index.md b/docs/markdown/index.md index 14bdfbe..427cc05 100644 --- a/docs/markdown/index.md +++ b/docs/markdown/index.md @@ -31,14 +31,16 @@ read [this beginner guide](SimpleStart.md) to get started. ## Community -There are two main methods of connecting with other Meson -developers. The easiest way for most people is a web chat. The channel -to use is `#mesonbuild` either via Matrix ([web +The easiest way for most people to connect to other Meson developers is +a web chat. The channel to use is `#mesonbuild` either via Matrix ([web interface](https://app.element.io/#/room/#mesonbuild:matrix.org)) or [OFTC IRC](https://www.oftc.net/). -The second one is the mailing list, which is hosted at -[Google Groups](https://groups.google.com/forum/#!forum/mesonbuild). +Other methods of communication include the [mailing +list](https://groups.google.com/forum/#!forum/mesonbuild) (hosted by +Google Groups) and the +[Discussions](https://github.com/mesonbuild/meson/discussions) section +of the Meson GitHub repository. ### [Projects using Meson](Users.md) diff --git a/docs/markdown/snippets/about_minimum_python_version.md b/docs/markdown/snippets/about_minimum_python_version.md new file mode 100644 index 0000000..fa44a75 --- /dev/null +++ b/docs/markdown/snippets/about_minimum_python_version.md @@ -0,0 +1,7 @@ +## Minimum required Python version updated to 3.7 + +Meson now requires at least Python version 3.7 to run as Python 3.6 reached EOL +on December 2021. In practice this should only affect people developing on +Ubuntu Bionic, who will need to manually install python3.8 from the official +repositories. + diff --git a/docs/markdown/snippets/armclang-support.md b/docs/markdown/snippets/armclang-support.md new file mode 100644 index 0000000..80e7af2 --- /dev/null +++ b/docs/markdown/snippets/armclang-support.md @@ -0,0 +1,6 @@ +## Support for ARM Ltd. Clang toolchain + +Support for the `armltdclang` compiler has been added. This differs from the +existing `armclang` toolchain in that it is a fork of Clang by ARM Ltd. and +supports native compilation. The Keil `armclang` toolchain only supports +cross-compilation to embedded devices. diff --git a/docs/markdown/snippets/check_false_warning.md b/docs/markdown/snippets/check_false_warning.md deleted file mode 100644 index 50214b7..0000000 --- a/docs/markdown/snippets/check_false_warning.md +++ /dev/null @@ -1,14 +0,0 @@ -## Warning if check kwarg of run_command is missing - -The `check` kwarg of `run_command` currently defaults to `false`. -Because we want to change that, running -```meson -run_command('cmd') -``` -now results in: -```text -WARNING: You should add the boolean check kwarg to the run_command call. - It currently defaults to false, - but it will default to true in future releases of meson. - See also: https://github.com/mesonbuild/meson/issues/9300 -``` diff --git a/docs/markdown/snippets/cmake_deprecated.md b/docs/markdown/snippets/cmake_deprecated.md deleted file mode 100644 index 9e456e7..0000000 --- a/docs/markdown/snippets/cmake_deprecated.md +++ /dev/null @@ -1,7 +0,0 @@ -## Support for CMake <3.14 is now deprecated for CMake subprojects - -In CMake 3.14, the File API was introduced and the old CMake server API was -deprecated (and removed in CMake 3.20). Thus support for this API will also -be removed from Meson in future releases. - -This deprecation only affects CMake subprojects. diff --git a/docs/markdown/snippets/extract-more-objects.md b/docs/markdown/snippets/extract-more-objects.md deleted file mode 100644 index 73a4757..0000000 --- a/docs/markdown/snippets/extract-more-objects.md +++ /dev/null @@ -1,4 +0,0 @@ -## ``extract_objects()`` supports generated sources - -Custom targets or generated files (returned by ``generator.process()``) -can now be passed to ``extract_objects()``. diff --git a/docs/markdown/snippets/fix_backend_startup_project.md b/docs/markdown/snippets/fix_backend_startup_project.md deleted file mode 100644 index 8269ef6..0000000 --- a/docs/markdown/snippets/fix_backend_startup_project.md +++ /dev/null @@ -1,4 +0,0 @@ -## backend_startup_project - -`backend_startup_project` will no longer erase the last project in a VS -solution if it is not the specified project. diff --git a/docs/markdown/snippets/install_symlink.md b/docs/markdown/snippets/install_symlink.md deleted file mode 100644 index 752c422..0000000 --- a/docs/markdown/snippets/install_symlink.md +++ /dev/null @@ -1,11 +0,0 @@ -## install_symlink function - -It is now possible to request for symbolic links to be installed during -installation. The `install_symlink` function takes a positional argument to -the link name, and installs a symbolic link pointing to `pointing_to` target. -The link will be created under `install_dir` directory and cannot contain path -separators. - -```meson -install_symlink('target', pointing_to: '../bin/target', install_dir: '/usr/sbin') -``` diff --git a/docs/markdown/snippets/removing_rpm_module.md b/docs/markdown/snippets/removing_rpm_module.md new file mode 100644 index 0000000..c492d51 --- /dev/null +++ b/docs/markdown/snippets/removing_rpm_module.md @@ -0,0 +1,10 @@ +## Removal of the RPM module + +Due to lack of interest, lack of maintainership, and lack of a clear purpose, +the RPM module has been removed. + +Users interested in one-shot tools to generate an RPM spec file template for +distro packaging, are encouraged develop an external tool that reads the +introspection data. + +For more details, see https://github.com/mesonbuild/meson/issues/9764 diff --git a/docs/markdown/snippets/rewriter_extra_files.md b/docs/markdown/snippets/rewriter_extra_files.md deleted file mode 100644 index c46f076..0000000 --- a/docs/markdown/snippets/rewriter_extra_files.md +++ /dev/null @@ -1,26 +0,0 @@ -## `meson rewrite` can modify `extra_files` - -The build script rewriter can now modify targets' `extra_files` lists, -or create them if absent. It it used in the same way as with rewriting -source lists: - -```bash -meson rewrite target <target name/id> {add_extra_files/rm_extra_files} [list of extra files] -``` - -The rewriter's script mode also supports these actions: - -```json -{ - "type": "target", - "target": "<target name>", - "operation": "extra_files_add / extra_files_rm", - "sources": ["list", "of", "extra", "files", "to", "add, remove"], -} -``` - -## `meson rewrite target <target> info` outputs *target*'s `extra_files` - -Targets' `extra_files` lists are now included in the rewriter's target info dump -as a list of file paths, in the same way `sources` are. This applies to both -`meson rewrite` CLI and script mode. diff --git a/docs/markdown/snippets/sccache.md b/docs/markdown/snippets/sccache.md deleted file mode 100644 index 72bdf5f..0000000 --- a/docs/markdown/snippets/sccache.md +++ /dev/null @@ -1,5 +0,0 @@ -## Added support for sccache - -Meson now supports [sccache](https://github.com/mozilla/sccache) just -like it has supported CCache. If both sccache and CCache are -available, the autodetection logic prefers sccache. diff --git a/docs/markdown/snippets/vs_2022.md b/docs/markdown/snippets/vs_2022.md deleted file mode 100644 index 0c3ff02..0000000 --- a/docs/markdown/snippets/vs_2022.md +++ /dev/null @@ -1,10 +0,0 @@ -## Visual Studio 2022 backend - -As Visual Studio 2022 is released recently, it's time to support the -new version in Meson. This mainly includes the new "v143" platform tools. - -The usage is similar to other backends. For example -```meson -meson setup builddir --backend=vs2022 -``` -will configure "builddir" for projects compatible with Visual Studio 2022. diff --git a/docs/markdown/snippets/windows_custom_targets.md b/docs/markdown/snippets/windows_custom_targets.md deleted file mode 100644 index cbc2f9d..0000000 --- a/docs/markdown/snippets/windows_custom_targets.md +++ /dev/null @@ -1,22 +0,0 @@ -## Windows.compile_resources CustomTarget - -Previously the Windows module only accepted CustomTargets with one output, it -now accepts them with more than one output, and creates a windows resource -target for each output. Additionally it now accepts indexes of CustomTargets - -```meson - -ct = custom_target( - 'multiple', - output : ['resource', 'another resource'], - ... -) - -ct2 = custom_target( - 'slice', - output : ['resource', 'not a resource'], - ... -) - -resources = windows.compile_resources(ct, ct2[0]) -``` diff --git a/docs/meson.build b/docs/meson.build index 53d4392..00e90ed 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -63,6 +63,22 @@ refman_json = custom_target( ], ) +refman_man = custom_target( + 'gen_refman_man', + build_by_default: true, + input: refman_binary, + output: 'meson-reference.3', + command: [ + genrefman, + '-l', 'pickle', + '-g', 'man', + '-i', '@INPUT@', + '-o', '@OUTPUT@', + '--force-color', + '--no-modules', + ], +) + test('validate_docs', find_program('./jsonvalidator.py'), args: [refman_json]) hotdoc_prog = find_program('hotdoc', version: '>=0.13.7') diff --git a/docs/refman/generatorbase.py b/docs/refman/generatorbase.py index e93166f..08ce492 100644 --- a/docs/refman/generatorbase.py +++ b/docs/refman/generatorbase.py @@ -43,6 +43,11 @@ class GeneratorBase(metaclass=ABCMeta): return f'0_{fn.name}' return sorted([x for x in raw if not x.hidden], key=key_fn) + @staticmethod + def _extract_meson_version() -> str: + from mesonbuild.coredata import version + return version + @property def functions(self) -> T.List[Function]: return GeneratorBase.sorted_and_filtered(self.manual.functions) diff --git a/docs/refman/generatorjson.py b/docs/refman/generatorjson.py index f5164d4..9f92342 100644 --- a/docs/refman/generatorjson.py +++ b/docs/refman/generatorjson.py @@ -92,13 +92,6 @@ class GeneratorJSON(GeneratorBase): 'methods': {x.name: self._generate_function(x) for x in self.sorted_and_filtered(obj.methods)}, } - def _extract_meson_version(self) -> str: - # Hack around python relative imports to get to the Meson version - import sys - sys.path.append(Path(__file__).resolve().parents[2].as_posix()) - from mesonbuild.coredata import version - return version - def generate(self) -> None: data: J.Root = { 'version_major': J.VERSION_MAJOR, diff --git a/docs/refman/generatorman.py b/docs/refman/generatorman.py new file mode 100644 index 0000000..dfd211f --- /dev/null +++ b/docs/refman/generatorman.py @@ -0,0 +1,382 @@ +import re +from pathlib import Path + +from .generatorbase import GeneratorBase +from .model import ( + ReferenceManual, + Function, + Object, + PosArg, + VarArgs, + Kwarg, +) + +import typing as T + + +class ManPage: + def __init__(self, path: Path): + self.path = path + self.text = "" + + def reset_font(self) -> None: + self.text += ".P\n" + + def title(self, name: str, section: int) -> None: + import datetime + + date = datetime.date.today() + self.reset_font() + self.text += f'.TH "{name}" "{section}" "{date}"\n' + + def section(self, name: str) -> None: + self.reset_font() + self.text += f".SH {name}\n" + + def subsection(self, name: str) -> None: + self.reset_font() + self.text += f".SS {name}\n" + + def par(self, text: str) -> None: + self.reset_font() + self.text += f"{text}\n" + + def indent(self, amount: int = 4) -> None: + self.text += f".RS {amount}\n" + + def unindent(self) -> None: + self.text += ".RE\n" + + def br(self) -> None: + self.text += ".br\n" + + def nl(self) -> None: + self.text += "\n" + + def line(self, text: str) -> None: + if text and text[0] in [".", "'"]: + self.text += "\\" + self.text += f"{text}\n" + + def inline(self, text: str) -> None: + self.text += f"{text}" + + def write(self) -> None: + self.path.write_text(self.text, encoding="utf-8") + + @staticmethod + def bold(text: str) -> str: + return f"\\fB{text}\\fR" + + @staticmethod + def italic(text: str) -> str: + return f"\\fI{text}\\fR" + + +class GeneratorMan(GeneratorBase): + def __init__( + self, manual: ReferenceManual, out: Path, enable_modules: bool + ) -> None: + super().__init__(manual) + self.out = out + self.enable_modules = enable_modules + self.links: T.List[str] = [] + + def generate_description(self, page: ManPage, desc: str) -> None: + def italicise(match: T.Match[str]) -> str: + v = match.group(1) + if v[0] == "@": + v = v[1:] + + return ManPage.italic(v) + + desc = re.sub(re.compile(r"\[\[(.*?)\]\]", re.DOTALL), italicise, desc) + + def linkify(match: T.Match[str]) -> str: + replacement = ManPage.italic(match.group(1)) + + if match.group(2)[0] != "#": + if match.group(2) in self.links: + num = self.links.index(match.group(2)) + else: + self.links.append(match.group(2)) + num = len(self.links) + + replacement += f"[{num}]" + + return replacement + + desc = re.sub(re.compile(r"\[(.*?)\]\((.*?)\)", re.DOTALL), linkify, desc) + + def bold(match: T.Match[str]) -> str: + return ManPage.bold(match.group(1)) + + desc = re.sub(re.compile(r"\*(.*?)\*"), bold, desc) + + isCode = False + for chunk in desc.split("```"): + if isCode: + page.indent() + lines = chunk.strip().split("\n") + if lines[0] == "meson": + lines = lines[1:] + + for line in lines: + page.line(line) + page.br() + page.unindent() + else: + inList = False + for line in chunk.strip().split("\n"): + if len(line) == 0: + page.nl() + if inList: + page.nl() + inList = False + elif line[0:2] in ["- ", "* "]: + if inList: + page.nl() + page.br() + else: + inList = True + + page.inline(line.strip() + " ") + elif inList and line[0] == " ": + page.inline(line.strip() + " ") + else: + inList = False + page.line(line) + + if inList: + page.nl() + + isCode = not isCode + + def function_name(self, f: Function, o: Object = None) -> str: + name = "" + if o is not None: + name += f"{o.name}." + + name += f.name + return name + + def generate_function_signature( + self, page: ManPage, f: Function, o: Object = None + ) -> None: + args = [] + + if f.posargs: + args += [arg.name for arg in f.posargs] + + if f.varargs: + args += [f.varargs.name + "..."] + + if f.optargs: + args += [f"[{arg.name}]" for arg in f.optargs] + + for kwarg in self.sorted_and_filtered(list(f.kwargs.values())): + kw = kwarg.name + ":" + if kwarg.default: + kw += " " + ManPage.bold(kwarg.default) + args += [kw] + + ret = ManPage.italic(f.returns.raw) + " " + + prefix = f"{ret}{self.function_name(f, o)}(" + sig = ", ".join(args) + suffix = ")" + + if len(prefix) + len(sig) + len(suffix) > 70: + page.line(prefix) + page.br() + page.indent() + for arg in args: + page.line(arg + ",") + page.br() + page.unindent() + page.line(suffix) + else: + page.line(prefix + sig + suffix) + + def base_info( + self, x: T.Union[PosArg, VarArgs, Kwarg, Function, Object] + ) -> T.List[str]: + info = [] + if x.deprecated: + info += [ManPage.bold("deprecated") + f" since {x.deprecated}"] + if x.since: + info += [f"since {x.since}"] + + return info + + def generate_function_arg( + self, + page: ManPage, + arg: T.Union[PosArg, VarArgs, Kwarg], + isOptarg: bool = False, + ) -> None: + required = ( + arg.required + if isinstance(arg, Kwarg) + else not isOptarg and not isinstance(arg, VarArgs) + ) + + page.line(ManPage.bold(arg.name)) + + info = [ManPage.italic(arg.type.raw)] + + if required: + info += [ManPage.bold("required")] + if isinstance(arg, (PosArg, Kwarg)) and arg.default: + info += [f"default: {arg.default}"] + if isinstance(arg, VarArgs): + mn = 0 if arg.min_varargs < 0 else arg.min_varargs + mx = "N" if arg.max_varargs < 0 else arg.max_varargs + info += [f"{mn}...{mx} times"] + + info += self.base_info(arg) + + page.line(", ".join(info)) + + page.br() + page.indent(2) + self.generate_description(page, arg.description.strip()) + page.unindent() + page.nl() + + def generate_function_argument_section( + self, + page: ManPage, + name: str, + args: T.Sequence[T.Union[PosArg, VarArgs, Kwarg]], + isOptarg: bool = False, + ) -> None: + if not args: + return + + page.line(ManPage.bold(name)) + page.indent() + for arg in args: + self.generate_function_arg(page, arg, isOptarg) + page.unindent() + + def generate_sub_sub_section( + self, page: ManPage, name: str, text: T.List[str], process: bool = True + ) -> None: + page.line(ManPage.bold(name)) + page.indent() + if process: + for line in text: + self.generate_description(page, line.strip()) + else: + page.line("\n\n".join([line.strip() for line in text])) + page.unindent() + + def generate_function(self, page: ManPage, f: Function, obj: Object = None) -> None: + page.subsection(self.function_name(f, obj) + "()") + page.indent(0) + + page.line(ManPage.bold("SYNOPSIS")) + page.indent() + self.generate_function_signature(page, f, obj) + + info = self.base_info(f) + if info: + page.nl() + page.line(", ".join(info)) + page.unindent() + page.nl() + + self.generate_sub_sub_section(page, "DESCRIPTION", [f.description]) + page.nl() + + self.generate_function_argument_section(page, "POSARGS", f.posargs) + if f.varargs: + self.generate_function_argument_section(page, "VARARGS", [f.varargs]) + self.generate_function_argument_section(page, "OPTARGS", f.optargs, True) + self.generate_function_argument_section( + page, "KWARGS", self.sorted_and_filtered(list(f.kwargs.values())) + ) + + if f.notes: + self.generate_sub_sub_section(page, "NOTES", f.notes) + if f.warnings: + self.generate_sub_sub_section(page, "WARNINGS", f.warnings) + if f.example: + self.generate_sub_sub_section(page, "EXAMPLE", [f.example]) + + page.unindent() + + def generate_object(self, page: ManPage, obj: Object) -> None: + page.subsection(obj.name) + page.indent(2) + + info = self.base_info(obj) + if info: + page.line(", ".join(info)) + page.br() + + if obj.extends: + page.line(ManPage.bold("extends: ") + obj.extends) + page.br() + + ret = [x.name for x in self.sorted_and_filtered(obj.returned_by)] + if ret: + page.line(ManPage.bold("returned_by: ") + ", ".join(ret)) + page.br() + + ext = [x.name for x in self.sorted_and_filtered(obj.extended_by)] + if ext: + page.line(ManPage.bold("extended_by: ") + ", ".join(ext)) + page.br() + + page.nl() + + self.generate_description(page, obj.description.strip()) + page.nl() + + if obj.notes: + self.generate_sub_sub_section(page, "NOTES", obj.notes) + if obj.warnings: + self.generate_sub_sub_section(page, "WARNINGS", obj.warnings) + if obj.example: + self.generate_sub_sub_section(page, "EXAMPLE", [obj.example]) + + page.unindent() + + def generate(self) -> None: + page = ManPage(self.out) + + page.title("meson-reference", 3) + + page.section("NAME") + page.par( + f"meson-reference v{self._extract_meson_version()}" + + " - a reference for meson functions and objects" + ) + + page.section("DESCRIPTION") + self.generate_description( + page, + """This manual is divided into two sections, *FUNCTIONS* and *OBJECTS*. *FUNCTIONS* contains a reference for all meson functions and methods. Methods are denoted by [[object_name]].[[method_name]](). *OBJECTS* contains additional information about each object.""", + ) + + page.section("FUNCTIONS") + for f in self.sorted_and_filtered(self.functions): + self.generate_function(page, f) + + for obj in self.sorted_and_filtered(self.objects): + for f in self.sorted_and_filtered(obj.methods): + self.generate_function(page, f, obj) + + page.section("OBJECTS") + for obj in self.sorted_and_filtered(self.objects): + self.generate_object(page, obj) + + page.section("SEE ALSO") + for i in range(len(self.links)): + link = self.links[i] + page.line(f"[{i + 1}] {link}") + page.br() + + page.write() diff --git a/docs/refman/main.py b/docs/refman/main.py index 5bc40f7..e2654c9 100644 --- a/docs/refman/main.py +++ b/docs/refman/main.py @@ -27,13 +27,14 @@ from .generatorjson import GeneratorJSON from .generatorprint import GeneratorPrint from .generatorpickle import GeneratorPickle from .generatormd import GeneratorMD +from .generatorman import GeneratorMan meson_root = Path(__file__).absolute().parents[2] def main() -> int: parser = argparse.ArgumentParser(description='Meson reference manual generator') parser.add_argument('-l', '--loader', type=str, default='yaml', choices=['yaml', 'pickle'], help='Information loader backend') - parser.add_argument('-g', '--generator', type=str, choices=['print', 'pickle', 'md', 'json'], required=True, help='Generator backend') + parser.add_argument('-g', '--generator', type=str, choices=['print', 'pickle', 'md', 'json', 'man'], required=True, help='Generator backend') parser.add_argument('-s', '--sitemap', type=Path, default=meson_root / 'docs' / 'sitemap.txt', help='Path to the input sitemap.txt') parser.add_argument('-o', '--out', type=Path, required=True, help='Output directory for generated files') parser.add_argument('-i', '--input', type=Path, default=meson_root / 'docs' / 'yaml', help='Input path for the selected loader') @@ -59,6 +60,7 @@ def main() -> int: 'pickle': lambda: GeneratorPickle(refMan, args.out), 'md': lambda: GeneratorMD(refMan, args.out, args.sitemap, args.link_defs, not args.no_modules), 'json': lambda: GeneratorJSON(refMan, args.out, not args.no_modules), + 'man': lambda: GeneratorMan(refMan, args.out, not args.no_modules), } generator = generators[args.generator]() diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 15564d7..82e0a7b 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -53,7 +53,6 @@ index.md Qt4-module.md Qt5-module.md Qt6-module.md - RPM-module.md Rust-module.md Simd-module.md SourceSet-module.md @@ -86,8 +85,8 @@ index.md Using-wraptool.md Wrap-best-practices-and-tips.md Shipping-prebuilt-binaries-as-wraps.md - fallback-wraptool.md Release-notes.md + Release-notes-for-0.61.0.md Release-notes-for-0.60.0.md Release-notes-for-0.59.0.md Release-notes-for-0.58.0.md diff --git a/docs/theme/extra/templates/navbar_links.html b/docs/theme/extra/templates/navbar_links.html index b8b6179..c518de5 100644 --- a/docs/theme/extra/templates/navbar_links.html +++ b/docs/theme/extra/templates/navbar_links.html @@ -23,7 +23,6 @@ ("Qt4-module.html","Qt4"), \ ("Qt5-module.html","Qt5"), \ ("Qt6-module.html","Qt6"), \ - ("RPM-module.html","RPM"), \ ("Rust-module.html","Rust"), \ ("Simd-module.html","Simd"), \ ("SourceSet-module.html","SourceSet"), \ diff --git a/docs/yaml/builtins/meson.yaml b/docs/yaml/builtins/meson.yaml index 4f2d24d..00ade2e 100644 --- a/docs/yaml/builtins/meson.yaml +++ b/docs/yaml/builtins/meson.yaml @@ -34,18 +34,17 @@ methods: posargs: script_name: - type: str | file | external_program | exe | custom_tgt | custom_idx + type: str | file | external_program description: | The script to execute. - *(since 0.55.0)* The output of [[configure_file]], [[files]], and [[find_program]] - as well as strings are accepted. + *(since 0.55.0)* The output of [[find_program]] as well as strings are accepted. *(since 0.57.0)* [[@file]] objects and the output of [[configure_file]] may be used. varargs: name: arg - type: str | file | external_program | exe | custom_tgt | custom_idx + type: str | file | external_program since: 0.49.0 description: | Additional arguments @@ -53,8 +52,6 @@ methods: *(since 0.55.0)* The output of [[configure_file]], [[files]], and [[find_program]] as well as strings are accepted. - *(since 0.57.0)* [[@file]] objects and the output of [[configure_file]] may be used. - - name: add_install_script returns: void description: | @@ -89,8 +86,26 @@ methods: shell would. If your script uses Python, `shlex.split()` is the easiest correct way to do this. - posargs_inherit: meson.add_dist_script - varargs_inherit: meson.add_dist_script + posargs: + script_name: + type: str | file | external_program | exe | custom_tgt | custom_idx + description: | + The script to execute. + + *(since 0.55.0)* The output of [[find_program]], [[executable]], + [[custom_target]], as well as strings are accepted. + + *(since 0.57.0)* [[@file]] objects and the output of [[configure_file]] may be used. + + varargs: + name: arg + type: str | file | external_program | exe | custom_tgt | custom_idx + since: 0.49.0 + description: | + Additional arguments + + *(since 0.55.0)* The output of [[find_program]], [[executable]], + [[custom_target]], as well as strings are accepted. kwargs: skip_if_destdir: diff --git a/docs/yaml/objects/cfg_data.yaml b/docs/yaml/objects/cfg_data.yaml index 9a66b73..5cc4b84 100644 --- a/docs/yaml/objects/cfg_data.yaml +++ b/docs/yaml/objects/cfg_data.yaml @@ -41,8 +41,17 @@ methods: type: str description: The name of the variable to set value: - type: bool - description: The value to set as either `1` or `0` + type: bool | int + description: | + The value to set as either `1` or `0` + + Passing numbers was never intended to work, and since 0.62 it has been + deprecated. It will be removed in a future version of Meson. If you + need to pass numbers use the `.set` method. + warnings: + - numeric values < 0 have the surprising behavior of being converted to + [[true]], values > 1 have the more expected but unintentional behavior of + being interpretered as [[true]]. kwargs_inherit: cfg_data.set diff --git a/docs/yaml/objects/dep.yaml b/docs/yaml/objects/dep.yaml index 23092c2..d847690 100644 --- a/docs/yaml/objects/dep.yaml +++ b/docs/yaml/objects/dep.yaml @@ -205,7 +205,7 @@ methods: default_value: type: str - description: The davault value to return when the variable does not exist + description: The default value to return when the variable does not exist pkgconfig_define: type: list[str] diff --git a/docs/yaml/objects/feature.yaml b/docs/yaml/objects/feature.yaml index 5b451e5..b6a754b 100644 --- a/docs/yaml/objects/feature.yaml +++ b/docs/yaml/objects/feature.yaml @@ -54,7 +54,7 @@ methods: if get_option('directx').require(host_machine.system() == 'windows', error_message: 'DirectX only available on Windows').allowed() then src += ['directx.c'] - config.set10('HAVE_DIRECTX', 1) + config.set10('HAVE_DIRECTX', true) endif ``` |