Chiebot-Mirror
/
meson
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #2224 from mesonbuild/morealpha

Browse Source 
More doc alphabetisation
pull/2227/head
Jussi Pakkanen 8 years ago committed by GitHub
parent 511a370856 9b5a5c2e61
commit 6fab0430be
16 changed files with 1691 additions and 512 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 171
      docs/markdown/Cross-compilation.md
  2. 197
      docs/markdown/Design-rationale.md
  3. 253
      docs/markdown/Gnome-module.md
  4. 4
      docs/markdown/Manual.md
  5. 44
      docs/markdown/Pkgconfig-module.md
  6. 15
      docs/markdown/Python-3-module.md
  7. 3
      docs/markdown/Qt4-module.md
  8. 13
      docs/markdown/Qt5-module.md
  9. 10
      docs/markdown/RPM-module.md
  10. 1214
      docs/markdown/Reference-manual.md
  11. 19
      docs/markdown/Reproducible-builds.md
  12. 11
      docs/markdown/Windows-module.md
  13. 93
      docs/markdown/Wrap-best-practices-and-tips.md
  14. 113
      docs/markdown/Wrap-dependency-system-manual.md
  15. 7
      docs/markdown/Wrap-review-guidelines.md
  16. 36
      docs/markdown/i18n-module.md

171
docs/markdown/Cross-compilation.md
Unescape View File

@ -4,28 +4,64 @@ short-description: Setting up cross-compilation
# Cross compilation
Meson has full support for cross compilation. Since cross compiling is more complicated than native building,
let's first go over some nomenclature. The three most important definitions are traditionally called *build*, *host* and *target*. This is confusing because those terms are used for quite many different things. To simplify the issue, we are going to call these the *build machine*, *host machine* and *target machine*. Their definitions are the following
Meson has full support for cross compilation. Since cross compiling is
more complicated than native building, let's first go over some
nomenclature. The three most important definitions are traditionally
called *build*, *host* and *target*. This is confusing because those
terms are used for quite many different things. To simplify the issue,
we are going to call these the *build machine*, *host machine* and
*target machine*. Their definitions are the following
* *build machine* is the computer that is doing the actual compiling
* *host machine* is the machine on which the compiled binary will run
* *target machine* is the machine on which the compiled binary's output will run (this is only meaningful for programs such as compilers that, when run, produce object code for a different CPU than what the program is being run on)
The `tl/dr` summary is the following: if you are doing regular cross compilation, you only care about *build_machine* and *host_machine*. Just ignore *target_machine* altogether and you will be correct 99% of the time. If your needs are more complex or you are interested in the actual details, do read on.
This might be easier to understand through examples. Let's start with the regular, not cross-compiling case. In these cases all of these three machines are the same. Simple so far.
Let's next look at the most common cross-compilation setup. Let's suppose you are on a 64 bit OSX machine and you are cross compiling a binary that will run on a 32 bit ARM Linux board. In this case your *build machine* is 64 bit OSX and both your *host* and *target machines* are 32 bit ARM Linux. This should be quite understandable as well.
It gets a bit trickier when we think about how the cross compiler was generated. It was built and it runs on a specific platform but the output it generates is for a different platform. In this case *build* and *host machines* are the same, but *target machine* is different.
The most complicated case is when you cross-compile a cross compiler. As an example you can, on a Linux machine, generate a cross compiler that runs on Windows but produces binaries on MIPS Linux. In this case *build machine* is x86 Linux, *host machine* is x86 Windows and *target machine* is MIPS Linux. This setup is known as the [Canadian Cross](https://en.wikipedia.org/wiki/Cross_compiler#Canadian_Cross). As a side note, be careful when reading cross compilation articles on Wikipedia or the net in general. It is very common for them to get build, host and target mixed up, even in consecutive sentences, which can leave you puzzled until you figure it out.
If you did not understand all of the details, don't worry. For most people it takes a while to wrap their head around these concepts. Don't panic, it might take a while to click, but you will get the hang of it eventually.
The `tl/dr` summary is the following: if you are doing regular cross
compilation, you only care about *build_machine* and
*host_machine*. Just ignore *target_machine* altogether and you will
be correct 99% of the time. If your needs are more complex or you are
interested in the actual details, do read on.
This might be easier to understand through examples. Let's start with
the regular, not cross-compiling case. In these cases all of these
three machines are the same. Simple so far.
Let's next look at the most common cross-compilation setup. Let's
suppose you are on a 64 bit OSX machine and you are cross compiling a
binary that will run on a 32 bit ARM Linux board. In this case your
*build machine* is 64 bit OSX and both your *host* and *target
machines* are 32 bit ARM Linux. This should be quite understandable as
well.
It gets a bit trickier when we think about how the cross compiler was
generated. It was built and it runs on a specific platform but the
output it generates is for a different platform. In this case *build*
and *host machines* are the same, but *target machine* is different.
The most complicated case is when you cross-compile a cross
compiler. As an example you can, on a Linux machine, generate a cross
compiler that runs on Windows but produces binaries on MIPS Linux. In
this case *build machine* is x86 Linux, *host machine* is x86 Windows
and *target machine* is MIPS Linux. This setup is known as the
[Canadian
Cross](https://en.wikipedia.org/wiki/Cross_compiler#Canadian_Cross). As
a side note, be careful when reading cross compilation articles on
Wikipedia or the net in general. It is very common for them to get
build, host and target mixed up, even in consecutive sentences, which
can leave you puzzled until you figure it out.
If you did not understand all of the details, don't worry. For most
people it takes a while to wrap their head around these
concepts. Don't panic, it might take a while to click, but you will
get the hang of it eventually.
## Defining the environment
Meson requires you to write a cross build definition file. It defines various properties of the cross build environment. The cross file consists of different sections. The first one is the list of executables that we are going to use. A sample snippet might look like this:
Meson requires you to write a cross build definition file. It defines
various properties of the cross build environment. The cross file
consists of different sections. The first one is the list of
executables that we are going to use. A sample snippet might look like
this:
```ini
[binaries]
@ -36,9 +72,17 @@ strip = '/usr/i586-mingw32msvc/bin/strip'
exe_wrapper = 'wine' # A command used to run generated executables.
```
The entries are pretty self explanatory but the last line is special. It defines a *wrapper command* that can be used to run executables for this host. In this case we can use Wine, which runs Windows applications on Linux. Other choices include running the application with qemu or a hardware simulator. If you have this kind of a wrapper, these lines are all you need to write. Meson will automatically use the given wrapper when it needs to run host binaries. This happens e.g. when running the project's test suite.
The entries are pretty self explanatory but the last line is
special. It defines a *wrapper command* that can be used to run
executables for this host. In this case we can use Wine, which runs
Windows applications on Linux. Other choices include running the
application with qemu or a hardware simulator. If you have this kind
of a wrapper, these lines are all you need to write. Meson will
automatically use the given wrapper when it needs to run host
binaries. This happens e.g. when running the project's test suite.
The next section lists properties of the cross compiler and thus of the target system. It looks like this:
The next section lists properties of the cross compiler and thus of
the target system. It looks like this:
```ini
[properties]
@ -56,16 +100,40 @@ c_args = ['-DCROSS=1', '-DSOMETHING=3']
c_link_args = ['-some_link_arg']
```
In most cases you don't need the size and alignment settings, Meson will detect all these by compiling and running some sample programs. If your build requires some piece of data that is not listed here, Meson will stop and write an error message describing how to fix the issue. If you need extra compiler arguments to be used during cross compilation you can set them with `[langname]_args = [args]`. Just remember to specify the args as an array and not as a single string (i.e. not as `'-DCROSS=1 -DSOMETHING=3'`).
One important thing to note, if you did not define an `exe_wrapper` in the previous section, is that Meson will make a best-effort guess at whether it can run the generated binaries on the build machine. It determines whether this is possible by looking at the `system` and `cpu_family` of build vs host. There will however be cases where they do match up, but the build machine is actually not compatible with the host machine. Typically this will happen if the libc used by the build and host machines are incompatible, or the code relies on kernel features not available on the build machine. One concrete example is a macOS build machine producing binaries for an iOS Simulator x86-64 host. They're both `darwin` and the same architecture, but their binaries are not actually compatible. In such cases you may use the `needs_exe_wrapper` property to override the auto-detection:
In most cases you don't need the size and alignment settings, Meson
will detect all these by compiling and running some sample
programs. If your build requires some piece of data that is not listed
here, Meson will stop and write an error message describing how to fix
the issue. If you need extra compiler arguments to be used during
cross compilation you can set them with `[langname]_args =
[args]`. Just remember to specify the args as an array and not as a
single string (i.e. not as `'-DCROSS=1 -DSOMETHING=3'`).
One important thing to note, if you did not define an `exe_wrapper` in
the previous section, is that Meson will make a best-effort guess at
whether it can run the generated binaries on the build machine. It
determines whether this is possible by looking at the `system` and
`cpu_family` of build vs host. There will however be cases where they
do match up, but the build machine is actually not compatible with the
host machine. Typically this will happen if the libc used by the build
and host machines are incompatible, or the code relies on kernel
features not available on the build machine. One concrete example is a
macOS build machine producing binaries for an iOS Simulator x86-64
host. They're both `darwin` and the same architecture, but their
binaries are not actually compatible. In such cases you may use the
`needs_exe_wrapper` property to override the auto-detection:
```ini
[properties]
needs_exe_wrapper = true
```
The last bit is the definition of host and target machines. Every cross build definition must have one or both of them. If it had neither, the build would not be a cross build but a native build. You do not need to define the build machine, as all necessary information about it is extracted automatically. The definitions for host and target machines look the same. Here is a sample for host machine.
The last bit is the definition of host and target machines. Every
cross build definition must have one or both of them. If it had
neither, the build would not be a cross build but a native build. You
do not need to define the build machine, as all necessary information
about it is extracted automatically. The definitions for host and
target machines look the same. Here is a sample for host machine.
```ini
[host_machine]
@ -75,11 +143,26 @@ cpu = 'i686'
endian = 'little'
```
These values define the machines sufficiently for cross compilation purposes. The corresponding target definition would look the same but have `target_machine` in the header. These values are available in your Meson scripts. There are three predefined variables called, surprisingly, `build_machine`, `host_machine` and `target_machine`. Determining the operating system of your host machine is simply a matter of calling `host_machine.system()`.
There are two different values for the CPU. The first one is `cpu_family`. It is a general type of the CPU. Common values might include `x86`, `arm` or `x86_64`. The second value is `cpu` which is a more specific subtype for the CPU. Typical values for a `x86` CPU family might include `i386` or `i586` and for `arm` family `armv5` or `armv7hl`. Note that CPU type strings are very system dependent. You might get a different value if you check its value on the same machine but with different operating systems.
If you do not define your host machine, it is assumed to be the build machine. Similarly if you do not specify target machine, it is assumed to be the host machine.
These values define the machines sufficiently for cross compilation
purposes. The corresponding target definition would look the same but
have `target_machine` in the header. These values are available in
your Meson scripts. There are three predefined variables called,
surprisingly, `build_machine`, `host_machine` and
`target_machine`. Determining the operating system of your host
machine is simply a matter of calling `host_machine.system()`.
There are two different values for the CPU. The first one is
`cpu_family`. It is a general type of the CPU. Common values might
include `x86`, `arm` or `x86_64`. The second value is `cpu` which is a
more specific subtype for the CPU. Typical values for a `x86` CPU
family might include `i386` or `i586` and for `arm` family `armv5` or
`armv7hl`. Note that CPU type strings are very system dependent. You
might get a different value if you check its value on the same machine
but with different operating systems.
If you do not define your host machine, it is assumed to be the build
machine. Similarly if you do not specify target machine, it is assumed
to be the host machine.
## Starting a cross build
@ -90,20 +173,24 @@ Once you have the cross file, starting a build is simple
$ meson srcdir builddir --cross-file cross_file.txt
```
Once configuration is done, compilation is started by invoking Ninja in the usual way.
Once configuration is done, compilation is started by invoking Ninja
in the usual way.
## Introspection and system checks
The main *meson* object provides two functions to determine cross compilation status.
The main *meson* object provides two functions to determine cross
compilation status.
```meson
meson.is_cross_build() # returns true when cross compiling
meson.has_exe_wrapper() # returns true if an exe wrapper has been defined
```
Note that the latter gives undefined return value when doing a native build.
Note that the latter gives undefined return value when doing a native
build.
You can run system checks on both the system compiler or the cross compiler. You just have to specify which one to use.
You can run system checks on both the system compiler or the cross
compiler. You just have to specify which one to use.
```meson
build_compiler = meson.get_compiler('c', native : true)
@ -115,7 +202,10 @@ host_int_size = host_compiler.sizeof('int')
## Mixing host and build targets
Sometimes you need to build a tool which is used to generate source files. These are then compiled for the actual target. For this you would want to build some targets with the system's native compiler. This requires only one extra keyword argument.
Sometimes you need to build a tool which is used to generate source
files. These are then compiled for the actual target. For this you
would want to build some targets with the system's native
compiler. This requires only one extra keyword argument.
```meson
native_exe = executable('mygen', 'mygen.c', native : true)
@ -125,22 +215,35 @@ You can then take `native_exe` and use it as part of a generator rule or anythin
## Using a custom standard library
Sometimes in cross compilation you need to build your own standard library instead of using the one provided by the compiler. Meson has built-in support for switching standard libraries transparently. The invocation to use in your cross file is the following:
Sometimes in cross compilation you need to build your own standard
library instead of using the one provided by the compiler. Meson has
built-in support for switching standard libraries transparently. The
invocation to use in your cross file is the following:
```ini
[properties]
c_stdlib = ['mylibc', 'mylibc_dep'] # Subproject name, dependency name
```
This specifies that C standard library is provided in the Meson subproject `mylibc` in internal dependency variable `mylibc_dep`. It is used on every cross built C target in the entire source tree (including subprojects) and the standard library is disabled. The build definitions of these targets do not need any modification.
This specifies that C standard library is provided in the Meson
subproject `mylibc` in internal dependency variable `mylibc_dep`. It
is used on every cross built C target in the entire source tree
(including subprojects) and the standard library is disabled. The
build definitions of these targets do not need any modification.
## Changing cross file settings
Cross file settings are only read when the build directory is set up the first time. Any changes to them after the fact will be ignored. This is the same as regular compiles where you can't change the compiler once a build tree has been set up. If you need to edit your cross file, then you need to wipe your build tree and recreate it from scratch.
Cross file settings are only read when the build directory is set up
the first time. Any changes to them after the fact will be
ignored. This is the same as regular compiles where you can't change
the compiler once a build tree has been set up. If you need to edit
your cross file, then you need to wipe your build tree and recreate it
from scratch.
## Custom data
You can store arbitrary data in `properties` and access them from your Meson files. As an example if you cross file has this:
You can store arbitrary data in `properties` and access them from your
Meson files. As an example if you cross file has this:
```ini
[properties]

197
docs/markdown/Design-rationale.md
Unescape View File

@ -5,76 +5,174 @@ title: Design rationale
This is the original design rationale for Meson. The syntax it describes does not match the released version
==
A software developer's most important tool is the editor. If you talk to coders about the editors they use, you are usually met with massive enthusiasm and praise. You will hear how Emacs is the greatest thing ever or how vi is so elegant or how Eclipse's integration features make you so much more productive. You can sense the enthusiasm and affection that the people feel towards these programs.
A software developer's most important tool is the editor. If you talk
to coders about the editors they use, you are usually met with massive
enthusiasm and praise. You will hear how Emacs is the greatest thing
ever or how vi is so elegant or how Eclipse's integration features
make you so much more productive. You can sense the enthusiasm and
affection that the people feel towards these programs.
The second most important tool, even more important than the compiler, is the build system.
The second most important tool, even more important than the compiler,
is the build system.
Those are pretty much universally despised.
The most positive statement on build systems you can usually get (and it might require some coaxing) is something along the lines of *well, it's a terrible system, but all other options are even worse*. It is easy to see why this is the case. For starters, commonly used free build systems have obtuse syntaxes. They use for the most part global variables that are set in random locations so you can never really be sure what a given line of code does. They do strange and unpredictable things at every turn.
Let's illustrate this with a simple example. Suppose we want to run a program built with GNU Autotools under GDB. The instinctive thing to do is to just run `gdb programname`. The problem is that this may or may not work. In some cases the executable file is a binary whereas at other times it is a wrapper shell script that invokes the real binary which resides in a hidden subdirectory. GDB invocation fails if the binary is a script but succeeds if it is not. The user has to remember the type of each one of his executables (which is an implementation detail of the build system) just to be able to debug them. Several other such pain points can be found in [this blog post](http://voices.canonical.com/jussi.pakkanen/2011/09/13/autotools/).
Given these idiosyncrasies it is no wonder that most people don't want to have anything to do with build systems. They'll just copy-paste code that works (somewhat) in one place to another and hope for the best. They actively go out of their way not to understand the system because the mere thought of it is repulsive. Doing this also provides a kind of inverse job security. If you don't know tool X, there's less chance of finding yourself responsible for its use in your organisation. Instead you get to work on more enjoyable things.
This leads to a vicious circle. Since people avoid the tools and don't want to deal with them, very few work on improving them. The result is apathy and stagnation.
The most positive statement on build systems you can usually get (and
it might require some coaxing) is something along the lines of *well,
it's a terrible system, but all other options are even worse*. It is
easy to see why this is the case. For starters, commonly used free
build systems have obtuse syntaxes. They use for the most part global
variables that are set in random locations so you can never really be
sure what a given line of code does. They do strange and unpredictable
things at every turn.
Let's illustrate this with a simple example. Suppose we want to run a
program built with GNU Autotools under GDB. The instinctive thing to
do is to just run `gdb programname`. The problem is that this may or
may not work. In some cases the executable file is a binary whereas at
other times it is a wrapper shell script that invokes the real binary
which resides in a hidden subdirectory. GDB invocation fails if the
binary is a script but succeeds if it is not. The user has to remember
the type of each one of his executables (which is an implementation
detail of the build system) just to be able to debug them. Several
other such pain points can be found in [this blog
post](http://voices.canonical.com/jussi.pakkanen/2011/09/13/autotools/).
Given these idiosyncrasies it is no wonder that most people don't want
to have anything to do with build systems. They'll just copy-paste
code that works (somewhat) in one place to another and hope for the
best. They actively go out of their way not to understand the system
because the mere thought of it is repulsive. Doing this also provides
a kind of inverse job security. If you don't know tool X, there's less
chance of finding yourself responsible for its use in your
organisation. Instead you get to work on more enjoyable things.
This leads to a vicious circle. Since people avoid the tools and don't
want to deal with them, very few work on improving them. The result is
apathy and stagnation.
Can we do better?
--
At its core, building C and C++ code is not a terribly difficult task. In fact, writing a text editor is a lot more complicated and takes more effort. Yet we have lots of very high quality editors but only few build systems with questionable quality and usability.
At its core, building C and C++ code is not a terribly difficult
task. In fact, writing a text editor is a lot more complicated and
takes more effort. Yet we have lots of very high quality editors but
only few build systems with questionable quality and usability.
So, in the grand tradition of own-itch-scratching, I decided to run a scientific experiment. The purpose of this experiment was to explore what would it take to build a "good" build system. What kind of syntax would suit this problem? What sort of problems would this application need to solve? What sort of solutions would be the most appropriate?
So, in the grand tradition of own-itch-scratching, I decided to run a
scientific experiment. The purpose of this experiment was to explore
what would it take to build a "good" build system. What kind of syntax
would suit this problem? What sort of problems would this application
need to solve? What sort of solutions would be the most appropriate?
To get things started, here is a list of requirements any modern cross-platform build system needs to provide.
###1. Must be simple to use###
One of the great virtues of Python is the fact that it is very readable. It is easy to see what a given block of code does. It is concise, clear and easy to understand. The proposed build system must be syntactically and semantically clean. Side effects, global state and interrelations must be kept at a minimum or, if possible, eliminated entirely.
One of the great virtues of Python is the fact that it is very
readable. It is easy to see what a given block of code does. It is
concise, clear and easy to understand. The proposed build system must
be syntactically and semantically clean. Side effects, global state
and interrelations must be kept at a minimum or, if possible,
eliminated entirely.
###2. Must do the right thing by default###
Most builds are done by developers working on the code. Therefore the defaults must be tailored towards that use case. As an example the system shall build objects without optimization and with debug information. It shall make binaries that can be run directly from the build directory without linker tricks, shell scripts or magic environment variables.
Most builds are done by developers working on the code. Therefore the
defaults must be tailored towards that use case. As an example the
system shall build objects without optimization and with debug
information. It shall make binaries that can be run directly from the
build directory without linker tricks, shell scripts or magic
environment variables.
###3. Must enforce established best practices###
There really is no reason to compile source code without the equivalent of `-Wall`. So enable it by default. A different kind of best practice is the total separation of source and build directories. All build artifacts must be stored in the build directory. Writing stray files in the source directory is not permitted under any circumstances.
There really is no reason to compile source code without the
equivalent of `-Wall`. So enable it by default. A different kind of
best practice is the total separation of source and build
directories. All build artifacts must be stored in the build
directory. Writing stray files in the source directory is not
permitted under any circumstances.
###4. Must have native support for platforms that are in common use###
A lot of free software projects can be used on non-free platforms such as Windows or OSX. The system must provide native support for the tools of choice on those platforms. In practice this means native support for Visual Studio and XCode. Having said IDEs invoke external builder binaries does not count as native support.
A lot of free software projects can be used on non-free platforms such
as Windows or OSX. The system must provide native support for the
tools of choice on those platforms. In practice this means native
support for Visual Studio and XCode. Having said IDEs invoke external
builder binaries does not count as native support.
###5. Must not add complexity due to obsolete platforms###
Work on this build system started during the Christmas holidays of 2012. This provides a natural hard cutoff line of 2012/12/24. Any platform, tool or library that was not in active use at that time is explicitly not supported. These include Unixes such as IRIX, SunOS, OSF-1, Ubuntu versions older than 12/10, GCC versions older than 4.7 and so on. If these old versions happen to work, great. If they don't, not a single line of code will be added to the system to work around their bugs.
Work on this build system started during the Christmas holidays of
2012. This provides a natural hard cutoff line of 2012/12/24. Any
platform, tool or library that was not in active use at that time is
explicitly not supported. These include Unixes such as IRIX, SunOS,
OSF-1, Ubuntu versions older than 12/10, GCC versions older than 4.7
and so on. If these old versions happen to work, great. If they don't,
not a single line of code will be added to the system to work around
their bugs.
###6. Must be fast###
Running the configuration step on a moderate sized project must not take more than five seconds. Running the compile command on a fully up to date tree of 1000 source files must not take more than 0.1 seconds.
Running the configuration step on a moderate sized project must not
take more than five seconds. Running the compile command on a fully up
to date tree of 1000 source files must not take more than 0.1 seconds.
###7. Must provide easy to use support for modern sw development features###
An example is precompiled headers. Currently no free software build system provides native support for them. Other examples could include easy integration of Valgrind and unit tests, test coverage reporting and so on.
An example is precompiled headers. Currently no free software build
system provides native support for them. Other examples could include
easy integration of Valgrind and unit tests, test coverage reporting
and so on.
###8. Must allow override of default values###
Sometimes you just have to compile files with only given compiler flags and no others, or install files in weird places. The system must allow the user to do this if he really wants to.
Sometimes you just have to compile files with only given compiler
flags and no others, or install files in weird places. The system must
allow the user to do this if he really wants to.
Overview of the solution
--
Going over these requirements it becomes quite apparent that the only viable approach is roughly the same as taken by CMake: having a domain specific language to declare the build system. Out of this declaration a configuration is generated for the backend build system. This can be a Makefile, Visual Studio or XCode project or anything else.
The difference between the proposed DSL and existing ones is that the new one is declarative. It also tries to work on a higher level of abstraction than existing systems. As an example, using external libraries in current build systems means manually extracting and passing around compiler flags and linker flags. In the proposed system the user just declares that a given build target uses a given external dependency. The build system then takes care of passing all flags and settings to their proper locations. This means that the user can focus on his own code rather than marshalling command line arguments from one place to another.
A DSL is more work than the approach taken by SCons, which is to provide the system as a Python library. However it allows us to make the syntax more expressive and prevent certain types of bugs by e.g. making certain objects truly immutable. The end result is again the same: less work for the user.
The backend for Unix requires a bit more thought. The default choice would be Make. However it is extremely slow. It is not uncommon on large code bases for Make to take several minutes just to determine that nothing needs to be done. Instead of Make we use [Ninja](https://ninja-build.org/), which is extremely fast. The backend code is abstracted away from the core, so other backends can be added with relatively little effort.
Going over these requirements it becomes quite apparent that the only
viable approach is roughly the same as taken by CMake: having a domain
specific language to declare the build system. Out of this declaration
a configuration is generated for the backend build system. This can be
a Makefile, Visual Studio or XCode project or anything else.
The difference between the proposed DSL and existing ones is that the
new one is declarative. It also tries to work on a higher level of
abstraction than existing systems. As an example, using external
libraries in current build systems means manually extracting and
passing around compiler flags and linker flags. In the proposed system
the user just declares that a given build target uses a given external
dependency. The build system then takes care of passing all flags and
settings to their proper locations. This means that the user can focus
on his own code rather than marshalling command line arguments from
one place to another.
A DSL is more work than the approach taken by SCons, which is to
provide the system as a Python library. However it allows us to make
the syntax more expressive and prevent certain types of bugs by
e.g. making certain objects truly immutable. The end result is again
the same: less work for the user.
The backend for Unix requires a bit more thought. The default choice
would be Make. However it is extremely slow. It is not uncommon on
large code bases for Make to take several minutes just to determine
that nothing needs to be done. Instead of Make we use
[Ninja](https://ninja-build.org/), which is extremely fast. The
backend code is abstracted away from the core, so other backends can
be added with relatively little effort.
Sample code
--
Enough design talk, let's get to the code. Before looking at the examples we would like to emphasize that this is not in any way the final code. It is proof of concept code that works in the system as it currently exists (February 2013), but may change at any time.
Enough design talk, let's get to the code. Before looking at the
examples we would like to emphasize that this is not in any way the
final code. It is proof of concept code that works in the system as it
currently exists (February 2013), but may change at any time.
Let's start simple. Here is the code to compile a single executable binary.
@ -83,9 +181,15 @@ project('compile one', 'c')
executable('program', 'prog.c')
```
This is about as simple as one can get. First you declare the project name and the languages it uses. Then you specify the binary to build and its sources. The build system will do all the rest. It will add proper suffixes (e.g. '.exe' on Windows), set the default compiler flags and so on.
This is about as simple as one can get. First you declare the project
name and the languages it uses. Then you specify the binary to build
and its sources. The build system will do all the rest. It will add
proper suffixes (e.g. '.exe' on Windows), set the default compiler
flags and so on.
Usually programs have more than one source file. Listing them all in the function call can become unwieldy. That is why the system supports keyword arguments. They look like this.
Usually programs have more than one source file. Listing them all in
the function call can become unwieldy. That is why the system supports
keyword arguments. They look like this.
```meson
project('compile several', 'c')
@ -102,9 +206,13 @@ sources = ['main.c', 'file1.c', 'file2.c', 'file3.c']
executable('program', sources : sourcelist, dep : libdep)
```
In other build systems you have to manually add the compile and link flags from external dependencies to targets. In this system you just declare that extlibrary is mandatory and that the generated program uses that. The build system does all the plumbing for you.
In other build systems you have to manually add the compile and link
flags from external dependencies to targets. In this system you just
declare that extlibrary is mandatory and that the generated program
uses that. The build system does all the plumbing for you.
Here's a slightly more complicated definition. It should still be understandable.
Here's a slightly more complicated definition. It should still be
understandable.
```meson
project('build library', 'c')
@ -114,20 +222,37 @@ exe = executable('testfoobar', 'tester.c', link : foolib)
add_test('test library', exe)
```
First we build a shared library named foobar. It is marked installable, so running `ninja install` installs it to the library directory (the system knows which one so the user does not have to care). Then we build a test executable which is linked against the library. It will no tbe installed, but instead it is added to the list of unit tests, which can be run with the command `ninja test`.
First we build a shared library named foobar. It is marked
installable, so running `ninja install` installs it to the library
directory (the system knows which one so the user does not have to
care). Then we build a test executable which is linked against the
library. It will no tbe installed, but instead it is added to the list
of unit tests, which can be run with the command `ninja test`.
Above we mentioned precompiled headers as a feature not supported by other build systems. Here's how you would use them.
Above we mentioned precompiled headers as a feature not supported by
other build systems. Here's how you would use them.
```meson
project('pch demo', 'cxx')
executable('myapp', 'myapp.cpp', pch : 'pch/myapp.hh')
```
The main reason other build systems can not provide pch support this easily is because they don't enforce certain best practices. Due to the way include paths work, it is impossible to provide pch support that always works with both in-source and out-of-source builds. Mandating separate build and source directories makes this and many other problems a lot easier.
The main reason other build systems can not provide pch support this
easily is because they don't enforce certain best practices. Due to
the way include paths work, it is impossible to provide pch support
that always works with both in-source and out-of-source
builds. Mandating separate build and source directories makes this and
many other problems a lot easier.
Get the code
--
The code for this experiment can be found at [the Meson repository](https://sourceforge.net/p/meson/code/). It should be noted that it is not a build system. It is only a proposal for one. It does not work reliably yet. You probably should not use it as the build system of your project.
The code for this experiment can be found at [the Meson
repository](https://sourceforge.net/p/meson/code/). It should be noted
that it is not a build system. It is only a proposal for one. It does
not work reliably yet. You probably should not use it as the build
system of your project.
All that said I hope that this experiment will eventually turn into a full blown build system. For that I need your help. Comments and especially patches are more than welcome.
All that said I hope that this experiment will eventually turn into a
full blown build system. For that I need your help. Comments and
especially patches are more than welcome.

253
docs/markdown/Gnome-module.md
Unescape View File

@ -1,68 +1,121 @@
# GNOME module
This module provides helper tools for build operations needed when building Gnome/GLib programs.
This module provides helper tools for build operations needed when
building Gnome/GLib programs.
**Note**: the compilation commands here might not work properly when you change the source files. This is a bug in the respective compilers which do not expose the required dependency information. This has been reported upstream in [this bug]. Until this is fixed you need to be careful when changing your source files.
**Note**: the compilation commands here might not work properly when
you change the source files. This is a bug in the respective
compilers which do not expose the required dependency
information. This has been reported upstream in [this bug]. Until
this is fixed you need to be careful when changing your source
files.
[this bug]: https://bugzilla.gnome.org/show_bug.cgi?id=745754
## Usage
To use this module, just do: **`gnome = import('gnome')`**. The following functions will then be available as methods on the object with the name `gnome`. You can, of course, replace the name `gnome` with anything else.
To use this module, just do: **`gnome = import('gnome')`**. The
following functions will then be available as methods on the object
with the name `gnome`. You can, of course, replace the name `gnome`
with anything else.
### gnome.compile_resources()
This function compiles resources specified in an XML file into code that can be embedded inside the main binary. Similar a build target it takes two positional arguments. The first one is the name of the resource and the second is the XML file containing the resource definitions. If the name is `foobar`, Meson will generate a header file called `foobar.h`, which you can then include in your sources.
This function compiles resources specified in an XML file into code
that can be embedded inside the main binary. Similar a build target it
takes two positional arguments. The first one is the name of the
resource and the second is the XML file containing the resource
definitions. If the name is `foobar`, Meson will generate a header
file called `foobar.h`, which you can then include in your sources.
* `c_name`: passed to the resource compiler as an argument after
`--c-name`
* `source_dir`: a list of subdirectories where the resource compiler should look up the files, relative to the location of the XML file
* `c_name`: passed to the resource compiler as an argument after `--c-name`
* `dependencies`: extra targets to depend upon for building
* `export`: (*Added 0.37.0*) if true, export the symbols of the generated sources
* `gresource_bundle`: (*Added 0.37.0*) if true, output a `.gresource` file instead of source
* `install_header`: (*Added 0.37.0*) if true, install the header file
* `export`: (*Added 0.37.0*) if true, export the symbols of the
generated sources
* `extra_args`: extra command line arguments to pass to the resource
* `gresource_bundle`: (*Added 0.37.0*) if true, output a `.gresource`
file instead of source
* `install`: (*Added 0.37.0*) if true, install the gresource file
* `install_dir`: (*Added 0.37.0*) location to install the header or bundle depending on previous options
* `extra_args`: extra command line arguments to pass to the resource compiler
Returns an array containing: `[c_source, header_file]` or `[gresource_bundle]`
* `install_dir`: (*Added 0.37.0*) location to install the header or
bundle depending on previous options
* `install_header`: (*Added 0.37.0*) if true, install the header file
* `source_dir`: a list of subdirectories where the resource compiler
should look up the files, relative to the location of the XML file
compiler
Returns an array containing: `[c_source, header_file]` or
`[gresource_bundle]`
### gnome.generate_gir()
Generates GObject introspection data. Takes one positional argument, the build target you want to build gir data for. There are several keyword arguments. Many of these map directly to the `g-ir-scanner` tool so see its documentation for more information.
Generates GObject introspection data. Takes one positional argument,
the build target you want to build gir data for. There are several
keyword arguments. Many of these map directly to the `g-ir-scanner`
tool so see its documentation for more information.
* `dependencies`: deps to use during introspection scanning
* `extra_args`: command line arguments to pass to gir compiler
* `export_packages`: extra packages the gir file exports
* `sources`: the list of sources to be scanned for gir data
* `nsversion`: namespace version
* `namespace`: the namespace for this gir object which determines output files
* `symbol_prefix`: the symbol prefix for the gir object, e.g. `gtk`
* `identifier_prefix`: the identifier prefix for the gir object, e.g. `Gtk`
* `export_packages`: extra packages the gir file exports
* `namespace`: the namespace for this gir object which determines
output files
* `identifier_prefix`: the identifier prefix for the gir object,
e.g. `Gtk`
* `includes`: list of gir names to be included, can also be a GirTarget
* `dependencies`: deps to use during introspection scanning
* `link_with`: list of libraries to link with
* `include_directories`: extra include paths to look for gir files
* `install`: if true, install the generated files
* `install_dir_gir`: (*Added 0.35.0*) which directory to install the gir file into
* `install_dir_typelib`: (*Added 0.35.0*) which directory to install the typelib file into
* `extra_args`: command line arguments to pass to gir compiler
Returns an array of two elements which are: `[gir_target, typelib_target]`
* `install_dir_gir`: (*Added 0.35.0*) which directory to install the
gir file into
* `install_dir_typelib`: (*Added 0.35.0*) which directory to install
the typelib file into
* `link_with`: list of libraries to link with
* `symbol_prefix`: the symbol prefix for the gir object, e.g. `gtk`
Returns an array of two elements which are: `[gir_target,
typelib_target]`
### gnome.genmarshal()
Generates a marshal file using the `glib-genmarshal` tool. The first argument is the basename of
the output files.
Generates a marshal file using the `glib-genmarshal` tool. The first
argument is the basename of the output files.
* `sources`: the list of sources to use as inputs
* `prefix`: the prefix to use for symbols
* `extra_args`: (*Added 0.42.0*) additional command line arguments to
pass
* `install_header`: if true, install the generated header
* `install_dir`: directory to install header to
* `stdinc`: if true, include the standard marshallers from glib
* `nostdinc`: if true, don't include the standard marshallers from glib
* `internal`: if true, mark generated sources as internal
* `nostdinc`: if true, don't include the standard marshallers from
glib
* `internal`: if true, mark generated sources as internal to
`glib-genmarshal` (*Requires GLib 2.54*)
* `prefix`: the prefix to use for symbols
* `skip_source`: if true, skip source location comments
* `stdinc`: if true, include the standard marshallers from glib
* `sources`: the list of sources to use as inputs
* `valist_marshallers`: if true, generate va_list marshallers
* `extra_args`: (*Added 0.42.0*) additional command line arguments to pass
to `glib-genmarshal` (*Requires GLib 2.54*)
*Added 0.35.0*
@ -70,23 +123,31 @@ Returns an array of two elements which are: `[c_source, header_file]`
### gnome.mkenums()
Generates enum files for GObject using the `glib-mkenums` tool. The first argument is the base name of the output files.
Generates enum files for GObject using the `glib-mkenums` tool. The
first argument is the base name of the output files.
This method is essentially a wrapper around the `glib-mkenums` tool's command line API. It is the most featureful method for enum creation.
This method is essentially a wrapper around the `glib-mkenums` tool's
command line API. It is the most featureful method for enum creation.
Typically you either provide template files or you specify the various template sections manually as strings.
Typically you either provide template files or you specify the various
template sections manually as strings.
Most libraries and applications will be using the same standard template with only minor tweaks, in which case the `gnome.mkenums_simple()` convenience method can be used instead.
Most libraries and applications will be using the same standard
template with only minor tweaks, in which case the
`gnome.mkenums_simple()` convenience method can be used instead.
Note that if you `#include` the generated header in any of the sources for a build target, you must add the generated header to the build target's list of sources to codify the dependency. This is true for all generated sources, not just `mkenums`.
Note that if you `#include` the generated header in any of the sources
for a build target, you must add the generated header to the build
target's list of sources to codify the dependency. This is true for
all generated sources, not just `mkenums`.
* `sources`: the list of sources to make enums with
* `c_template`: template to use for generating the source
* `comments`: comment passed to the command
* `h_template`: template to use for generating the header
* `identifier_prefix`: prefix to use for the identifiers
* `install_header`: if true, install the generated header
* `install_dir`: directory to install the header
* `comments`: comment passed to the command
* `identifier_prefix`: prefix to use for the identifiers
* `sources`: the list of sources to make enums with
* `symbol_prefix`: prefix to use for the symbols
* `eprod`: enum text
* `fhead`: file header
@ -101,24 +162,31 @@ Returns an array of two elements which are: `[c_source, header_file]`
### gnome.mkenums_simple()
Generates enum `.c` and `.h` files for GObject using the `glib-mkenums` tool
with the standard template used by most GObject-based C libraries. The first
argument is the base name of the output files.
Note that if you `#include` the generated header in any of the sources for a
build target, you must add the generated header to the build target's list of
sources to codify the dependency. This is true for all generated sources, not
just `mkenums_simple`.
* `sources`: the list of sources to make enums with
Generates enum `.c` and `.h` files for GObject using the
`glib-mkenums` tool with the standard template used by most
GObject-based C libraries. The first argument is the base name of the
output files.
Note that if you `#include` the generated header in any of the sources
for a build target, you must add the generated header to the build
target's list of sources to codify the dependency. This is true for
all generated sources, not just `mkenums_simple`.
* `body_prefix`: additional prefix at the top of the body file,
e.g. for extra includes
* `decorator`: optional decorator for the function declarations,
e.g. `GTK_AVAILABLE` or `GST_EXPORT`
* `function_prefix`: additional prefix for function names, e.g. in
case you want to add a leading underscore to functions used only
internally
* `header_prefix`: additional prefix at the top of the header file,
e.g. for extra includes (which may be needed if you specify a
decorator for the function declarations)
* `install_header`: if true, install the generated header
* `install_dir`: directory to install the header
* `identifier_prefix`: prefix to use for the identifiers
* `sources`: the list of sources to make enums with
* `symbol_prefix`: prefix to use for the symbols
* `header_prefix`: additional prefix at the top of the header file, e.g. for extra includes (which may be needed if you specify a decorator for the function declarations)
* `decorator`: optional decorator for the function declarations, e.g. `GTK_AVAILABLE` or `GST_EXPORT`
* `function_prefix`: additional prefix for function names, e.g. in case you want to add a leading underscore to functions used only internally
* `body_prefix`: additional prefix at the top of the body file, e.g. for extra includes
Example:
@ -144,68 +212,87 @@ Returns an array of two elements which are: `[c_source, header_file]`
### gnome.compile_schemas()
When called, this method will compile the gschemas in the current directory. Note that this is not
for installing schemas and is only useful when running the application locally for example during tests.
When called, this method will compile the gschemas in the current
directory. Note that this is not for installing schemas and is only
useful when running the application locally for example during tests.
### gnome.gdbus_codegen()
Compiles the given XML schema into gdbus source code. Takes two positional arguments, the first one specifies the name of the source files and the second specifies the XML file name. There are three keyword arguments. `interface_prefix` and `namespace` map to corresponding features of the compiler while `object_manager` (since 0.40.0), when set to true, generates object manager code.
Compiles the given XML schema into gdbus source code. Takes two
positional arguments, the first one specifies the name of the source
files and the second specifies the XML file name. There are three
keyword arguments. `interface_prefix` and `namespace` map to
corresponding features of the compiler while `object_manager` (since
0.40.0), when set to true, generates object manager code.
Returns an opaque object containing the source files. Add it to a top level target's source list.
Returns an opaque object containing the source files. Add it to a top
level target's source list.
### gnome.generate_vapi()
Creates a VAPI file from gir. The first argument is the name of the library.
Creates a VAPI file from gir. The first argument is the name of the
library.
* `sources`: the gir source to generate the VAPI from
* `packages`: VAPI packages that are depended upon
* `metadata_dirs`: extra directories to include for metadata files
* `gir_dirs`: extra directories to include for gir files
* `vapi_dirs`: extra directories to include for VAPI files
* `install`: if true, install the VAPI file
* `install_dir`: location to install the VAPI file (defaults to datadir/vala/vapi)
* `metadata_dirs`: extra directories to include for metadata files
* `packages`: VAPI packages that are depended upon
* `sources`: the gir source to generate the VAPI from
* `vapi_dirs`: extra directories to include for VAPI files
Returns a custom dependency that can be included when building other VAPI or Vala binaries.
Returns a custom dependency that can be included when building other
VAPI or Vala binaries.
*Added 0.36.0*
### gnome.yelp()
Installs help documentation using Yelp. The first argument is the project id.
Installs help documentation using Yelp. The first argument is the
project id.
This also creates two targets for translations `help-$project-update-po` and `help-$project-pot`.
This also creates two targets for translations
`help-$project-update-po` and `help-$project-pot`.
* `sources`: list of pages
* `languages`: list of languages for translations
* `media`: list of media such as images
* `sources`: list of pages
* `symlink_media`: if media should be symlinked not copied (defaults to `true` since 0.42.0)
* `languages`: list of languages for translations
Note that very old versions of yelp may not support symlinked media; At least 3.10 should work.
Note that very old versions of yelp may not support symlinked media;
At least 3.10 should work.
*Added 0.36.0*
### gnome.gtkdoc()
Compiles and installs gtkdoc documentation into `prefix/share/gtk-doc/html`. Takes one positional argument: The name of the module.
Compiles and installs gtkdoc documentation into
`prefix/share/gtk-doc/html`. Takes one positional argument: The name
of the module.
* `main_xml`: specifies the main XML file
* `main_sgml`: equal to `main_xml`
* `src_dir`: include_directories to include
* `content_files`: a list of content files
* `dependencies`: a list of dependencies
* `install`: if true, installs the generated docs
* `install_dir`: the directory to install the generated docs relative to the gtk-doc html dir or an absolute path (default: module name)
* `scan_args`: a list of arguments to pass to `gtkdoc-scan`
* `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj`
* `gobject_typesfile`: a list of type files
* `fixxref_args`: a list of arguments to pass to `gtkdoc-fixxref`
* `html_args` a list of arguments to pass to `gtkdoc-mkhtml`
* `gobject_typesfile`: a list of type files
* `ignore_headers`: a list of header files to ignore
* `html_assets`: a list of assets for the HTML pages
* `content_files`: a list of content files
* `html_args` a list of arguments to pass to `gtkdoc-mkhtml`
* `install`: if true, installs the generated docs
* `install_dir`: the directory to install the generated docs relative
to the gtk-doc html dir or an absolute path (default: module name)
* `main_xml`: specifies the main XML file
* `main_sgml`: equal to `main_xml`
* `mkdb_args`: a list of arguments to pass to `gtkdoc-mkdb`
* `ignore_headers`: a list of header files to ignore
* `scan_args`: a list of arguments to pass to `gtkdoc-scan`
* `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj`
* `src_dir`: include_directories to include
This creates a `$module-doc` target that can be ran to build docs and normally these are only built on install.
This creates a `$module-doc` target that can be ran to build docs and
normally these are only built on install.
### gnome.gtkdoc_html_dir()
Takes as argument a module name and returns the path where that module's HTML files will be installed. Usually used with `install_data` to install extra files, such as images, to the output directory.
Takes as argument a module name and returns the path where that
module's HTML files will be installed. Usually used with
`install_data` to install extra files, such as images, to the output
directory.

4
docs/markdown/Manual.md
Unescape View File

@ -4,4 +4,6 @@ short-description: User manual for Meson
# Manual
This is the user manual for Meson. It currently tracks the state of Git head. If you are using an older version, some of the information here might not work for you.
This is the user manual for Meson. It currently tracks the state of
Git head. If you are using an older version, some of the information
here might not work for you.

44
docs/markdown/Pkgconfig-module.md
Unescape View File

@ -1,24 +1,42 @@
# Pkgconfig module
This module is a simple generator for [pkg-config](https://pkg-config.freedesktop.org/) files.
This module is a simple generator for
[pkg-config](https://pkg-config.freedesktop.org/) files.
## Usage
To use this module, just do: **`pkg = import('pkgconfig')`**. The following function will then be available as `pkg.generate()`. You can, of course, replace the name `pkg` with anything else.
To use this module, just do: **`pkg = import('pkgconfig')`**. The
following function will then be available as `pkg.generate()`. You
can, of course, replace the name `pkg` with anything else.
### pkg.generate()
The generated file's properties are specified with the following keyword arguments.
The generated file's properties are specified with the following
keyword arguments.
- `libraries` a list of built libraries (usually results of shared_library) that the user needs to link against
- `version` a string describing the version of this library
- `name` the name of this library
- `description` a string describing the library
- `filebase`, the base name to use for the pkg-config file, as an example the value of `libfoo` would produce a pkg-config file called `libfoo.pc`
- `subdirs` which subdirs of `include` should be added to the header search path, for example if you install headers into `${PREFIX}/include/foobar-1`, the correct value for this argument would be `foobar-1`
- `extra_cflags` a list of extra compiler flags to be added to the
`Cflags` field after the header search path
- `filebase`, the base name to use for the pkg-config file, as an
example the value of `libfoo` would produce a pkg-config file called
`libfoo.pc`
- `install_dir` the directory to install to, defaults to the value of
option `libdir` followed by `/pkgconfig`
- `libraries` a list of built libraries (usually results of
shared_library) that the user needs to link against
- `libraries_private` list of strings to put in the
`Libraries.private` field
- `name` the name of this library
- `subdirs` which subdirs of `include` should be added to the header
search path, for example if you install headers into
`${PREFIX}/include/foobar-1`, the correct value for this argument
would be `foobar-1`
- `requires` list of strings to put in the `Requires` field
- `requires_private` list of strings to put in the `Requires.private` field
- `libraries_private` list of strings to put in the `Libraries.private` field
- `install_dir` the directory to install to, defaults to the value of option `libdir` followed by `/pkgconfig`
- `extra_cflags` a list of extra compiler flags to be added to the `Cflags` field after the header search path
- `variables` a list of strings with custom variables to add to the generated file. The strings must be in the form `name=value` and may reference other pkgconfig variables, e.g. `datadir=${prefix}/share`. The names `prefix`, `libdir` and `installdir` are reserved and may not be used.
- `requires_private` list of strings to put in the `Requires.private`
field
- `variables` a list of strings with custom variables to add to the
generated file. The strings must be in the form `name=value` and may
reference other pkgconfig variables,
e.g. `datadir=${prefix}/share`. The names `prefix`, `libdir` and
`installdir` are reserved and may not be used.
- `version` a string describing the version of this library

15
docs/markdown/Python-3-module.md
Unescape View File

@ -1,16 +1,22 @@
# Python 3 module
This module provides support for dealing with Python 3. It has the following methods.
This module provides support for dealing with Python 3. It has the
following methods.
## find_python
This is a cross platform way of finding the Python 3 executable, which may have a different name on different operating systems. Returns an external program object.
This is a cross platform way of finding the Python 3 executable, which
may have a different name on different operating systems. Returns an
external program object.
*Added 0.38.0*
## extension_module
Creates a `shared_module` target that is named according to the naming conventions of the target platform. All positional and keyword arguments are the same as for [shared_module](Reference-manual.md#shared_module).
Creates a `shared_module` target that is named according to the naming
conventions of the target platform. All positional and keyword
arguments are the same as for
[shared_module](Reference-manual.md#shared_module).
*Added 0.38.0*
@ -22,6 +28,7 @@ Returns a string with the Python language version such as `3.5`.
## sysconfig_path
Returns the Python sysconfig path without prefix, such as `lib/python3.6/site-packages`.
Returns the Python sysconfig path without prefix, such as
`lib/python3.6/site-packages`.
*Added 0.40.0*

3
docs/markdown/Qt4-module.md
Unescape View File

@ -1,3 +1,4 @@
# Qt4 module
This module provides support for Qt4's `moc`, `uic` and `rcc` tools. It is used identically to the [Qt 5 module](Qt5-module.md).
This module provides support for Qt4's `moc`, `uic` and `rcc`
tools. It is used identically to the [Qt 5 module](Qt5-module.md).

13
docs/markdown/Qt5-module.md
Unescape View File

@ -1,10 +1,15 @@
# Qt5 module
The Qt5 module provides tools to automatically deal with the various tools and steps required for Qt. The module has one method.
The Qt5 module provides tools to automatically deal with the various
tools and steps required for Qt. The module has one method.
## preprocess
This method takes four keyword arguments, `moc_headers`, `moc_sources`, `ui_files` and `qresources` which define the files that require preprocessing with `moc`, `uic` and `rcc`. It returns an opaque object that should be passed to a main build target. A simple example would look like this:
This method takes four keyword arguments, `moc_headers`,
`moc_sources`, `ui_files` and `qresources` which define the files that
require preprocessing with `moc`, `uic` and `rcc`. It returns an
opaque object that should be passed to a main build target. A simple
example would look like this:
```meson
qt5 = import('qt5')
@ -15,4 +20,6 @@ executable('myprog', 'main.cpp', 'myclass.cpp', moc_files,
```
The 'modules' argument is used to include Qt modules in the project. See the Qt documentation for the [list of modules](http://doc.qt.io/qt-5/qtmodules.html).
The 'modules' argument is used to include Qt modules in the project.
See the Qt documentation for the [list of
modules](http://doc.qt.io/qt-5/qtmodules.html).

10
docs/markdown/RPM-module.md
Unescape View File

@ -1,10 +1,16 @@
# 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.
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.
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.

1214
docs/markdown/Reference-manual.md
View File

File diff suppressed because it is too large Load Diff

19
docs/markdown/Reproducible-builds.md
Unescape View File

@ -1,9 +1,20 @@
# Reproducible builds
A reproducible build means the following (as quoted from [the reproducible builds project site](https://reproducible-builds.org/)):
A reproducible build means the following (as quoted from [the
reproducible builds project site](https://reproducible-builds.org/)):
> Reproducible builds are a set of software development practices that create a verifiable path from human readable source code to the binary code used by computers.
> Reproducible builds are a set of software development practices that
create a verifiable path from human readable source code to the
binary code used by computers.
Roughly what this means is that if two different people compile the project from source, their outputs are bitwise identical to each other. This allows people to verify that binaries downloadable from the net actually come from the corresponding sources and have not, for example, had malware added to them.
Roughly what this means is that if two different people compile the
project from source, their outputs are bitwise identical to each
other. This allows people to verify that binaries downloadable from
the net actually come from the corresponding sources and have not, for
example, had malware added to them.
Meson aims to support reproducible builds out of the box with zero additional work (assuming the rest of the build environment is set up for reproducibility). If you ever find a case where this is not happening, it is a bug. Please file an issue with as much information as possible and we'll get it fixed.
Meson aims to support reproducible builds out of the box with zero
additional work (assuming the rest of the build environment is set up
for reproducibility). If you ever find a case where this is not
happening, it is a bug. Please file an issue with as much information
as possible and we'll get it fixed.

11
docs/markdown/Windows-module.md
Unescape View File

@ -1,12 +1,17 @@
# Windows module
This module provides functionality used to build applications for Windows.
This module provides functionality used to build applications for
Windows.
## Methods
### compile_resources
Compiles Windows `rc` files specified in the positional arguments. Returns an opaque object that you put in the list of sources for the target you want to have the resources in. This method has the following keyword argument.
Compiles Windows `rc` files specified in the positional
arguments. Returns an opaque object that you put in the list of
sources for the target you want to have the resources in. This method
has the following keyword argument.
- `args` lists extra arguments to pass to the resource compiler
- `include_directories` which does the same thing as it does on target declarations: specifies header search directories
- `include_directories` which does the same thing as it does on target
declarations: specifies header search directories

93
docs/markdown/Wrap-best-practices-and-tips.md
Unescape View File

@ -1,14 +1,29 @@
# Wrap best practices and tips
There are several things you need to take into consideration when writing a Meson build definition for a project. This is especially true when the project will be used as a subproject. This page lists a few things to consider when writing your definitions.
There are several things you need to take into consideration when
writing a Meson build definition for a project. This is especially
true when the project will be used as a subproject. This page lists a
few things to consider when writing your definitions.
## Do not put config.h in external search path
Many projects use a `config.h` header file that they use for configuring their project internally. These files are never installed to the system header files so there are no inclusion collisions. This is not the case with subprojects, your project tree may have an arbitrary number of configuration files, so we need to ensure they don't clash.
Many projects use a `config.h` header file that they use for
configuring their project internally. These files are never installed
to the system header files so there are no inclusion collisions. This
is not the case with subprojects, your project tree may have an
arbitrary number of configuration files, so we need to ensure they
don't clash.
The basic problem is that the users of the subproject must be able to include subproject headers without seeing its `config.h` file. The most correct solution is to rename the `config.h` file into something unique, such as `foobar-config.h`. This is usually not feasible unless you are the maintainer of the subproject in question.
The basic problem is that the users of the subproject must be able to
include subproject headers without seeing its `config.h` file. The
most correct solution is to rename the `config.h` file into something
unique, such as `foobar-config.h`. This is usually not feasible unless
you are the maintainer of the subproject in question.
The pragmatic solution is to put the config header in a directory that has no other header files and then hide that from everyone else. One way is to create a top level subdirectory called `internal` and use that to build your own sources, like this:
The pragmatic solution is to put the config header in a directory that
has no other header files and then hide that from everyone else. One
way is to create a top level subdirectory called `internal` and use
that to build your own sources, like this:
```meson
subdir('internal') # create config.h in this subdir
@ -16,7 +31,9 @@ internal_inc = include_directories('internal')
shared_library('foo', 'foo.c', include_directories : internal_inc)
```
Many projects keep their `config.h` in the top level directory that has no other source files in it. In that case you don't need to move it but can just do this instead:
Many projects keep their `config.h` in the top level directory that
has no other source files in it. In that case you don't need to move
it but can just do this instead:
```meson
internal_inc = include_directories('.') # At top level meson.build
@ -24,9 +41,15 @@ internal_inc = include_directories('.') # At top level meson.build
## Make libraries buildable both as static and shared
Some platforms (e.g. iOS) requires linking everything in your main app statically. In other cases you might want shared libraries. They are also faster during development due to Meson's relinking optimization. However building both library types on all builds is slow and wasteful.
Some platforms (e.g. iOS) requires linking everything in your main app
statically. In other cases you might want shared libraries. They are
also faster during development due to Meson's relinking
optimization. However building both library types on all builds is
slow and wasteful.
Your project should provide a toggle specifying which type of library it should build. As an example if you have a Meson option called `shared_lib` then you could do this:
Your project should provide a toggle specifying which type of library
it should build. As an example if you have a Meson option called
`shared_lib` then you could do this:
```meson
if get_option('shared_lib')
@ -41,9 +64,18 @@ mylib = build_target('foo', 'foo.c',
## Declare generated headers explicitly
Meson's Ninja backend works differently from Make and other systems. Rather than processing things directory per directory, it looks at the entire build definition at once and runs the individual compile jobs in what might look to the outside as a random order.
Meson's Ninja backend works differently from Make and other
systems. Rather than processing things directory per directory, it
looks at the entire build definition at once and runs the individual
compile jobs in what might look to the outside as a random order.
The reason for this is that this is much more efficient so your builds finish faster. The downside is that you have to be careful with your dependencies. The most common problem here is headers that are generated at compile time with e.g. code generators. If these headers are needed when building code that uses these libraries, the compile job might be run before the code generation step. The fix is to make the dependency explicit like this:
The reason for this is that this is much more efficient so your builds
finish faster. The downside is that you have to be careful with your
dependencies. The most common problem here is headers that are
generated at compile time with e.g. code generators. If these headers
are needed when building code that uses these libraries, the compile
job might be run before the code generation step. The fix is to make
the dependency explicit like this:
```meson
myheader = custom_target(...)
@ -64,9 +96,18 @@ Meson will ensure that the header file has been built before compiling `main.c`.
## Avoid exposing compilable source files in declare_dependency
The main use for the `sources` argument in `declare_dependency` is to construct the correct dependency graph for the backends, as demonstrated in the previous section. It is extremely important to note that it should *not* be used to directly expose compilable sources (`.c`, `.cpp`, etc.) of dependencies, and should rather only be used for header/config files. The following example will illustrate what can go wrong if you accidentally expose compilable source files.
The main use for the `sources` argument in `declare_dependency` is to
construct the correct dependency graph for the backends, as
demonstrated in the previous section. It is extremely important to
note that it should *not* be used to directly expose compilable
sources (`.c`, `.cpp`, etc.) of dependencies, and should rather only
be used for header/config files. The following example will illustrate
what can go wrong if you accidentally expose compilable source files.
So you've read about unity builds and how Meson natively supports them. You decide to expose the sources of dependencies in order to have unity builds that include their dependencies. For your support library you do
So you've read about unity builds and how Meson natively supports
them. You decide to expose the sources of dependencies in order to
have unity builds that include their dependencies. For your support
library you do
```meson
my_support_sources = files(...)
@ -96,6 +137,30 @@ myexe = executable(
...)
```
This is extremely dangerous. When building, `mylibrary` will build and link the support sources `my_support_sources` into the resulting shared library. Then, for `myexe`, these same support sources will be compiled again, will be linked into the resulting executable, in addition to them being already present in `mylibrary`. This can quickly run afoul of the [One Definition Rule (ODR)](https://en.wikipedia.org/wiki/One_Definition_Rule) in C++, as you have more than one definition of a symbol, yielding undefined behavior. While C does not have a strict ODR rule, there is no language in the standard which guarantees such behavior to work. Violations of the ODR can lead to weird idiosyncratic failures such as segfaults. In the overwhelming number of cases, exposing library sources via the `sources` argument in `declare_dependency` is thus incorrect. If you wish to get full cross-library performance, consider building `mysupportlib` as a static library instead and employing LTO.
There are exceptions to this rule. If there are some natural constraints on how your library is to be used, you can expose sources. For instance, the WrapDB module for GoogleTest directly exposes the sources of GTest and GMock. This is valid, as GTest and GMock will only ever be used in *terminal* link targets. A terminal target is the final target in a dependency link chain, for instance `myexe` in the last example, whereas `mylibrary` is an intermediate link target. For most libraries this rule is not applicable though, as you cannot in general control how others consume your library, and as such should not expose sources.
This is extremely dangerous. When building, `mylibrary` will build and
link the support sources `my_support_sources` into the resulting
shared library. Then, for `myexe`, these same support sources will be
compiled again, will be linked into the resulting executable, in
addition to them being already present in `mylibrary`. This can
quickly run afoul of the [One Definition Rule
(ODR)](https://en.wikipedia.org/wiki/One_Definition_Rule) in C++, as
you have more than one definition of a symbol, yielding undefined
behavior. While C does not have a strict ODR rule, there is no
language in the standard which guarantees such behavior to
work. Violations of the ODR can lead to weird idiosyncratic failures
such as segfaults. In the overwhelming number of cases, exposing
library sources via the `sources` argument in `declare_dependency` is
thus incorrect. If you wish to get full cross-library performance,
consider building `mysupportlib` as a static library instead and
employing LTO.
There are exceptions to this rule. If there are some natural
constraints on how your library is to be used, you can expose
sources. For instance, the WrapDB module for GoogleTest directly
exposes the sources of GTest and GMock. This is valid, as GTest and
GMock will only ever be used in *terminal* link targets. A terminal
target is the final target in a dependency link chain, for instance
`myexe` in the last example, whereas `mylibrary` is an intermediate
link target. For most libraries this rule is not applicable though, as
you cannot in general control how others consume your library, and as
such should not expose sources.

113
docs/markdown/Wrap-dependency-system-manual.md
Unescape View File

@ -1,16 +1,36 @@
# Wrap dependency system manual
One of the major problems of multiplatform development is wrangling all your dependencies. This is easy on Linux where you can use system packages but awkward on other platforms. Most of those do not have a package manager at all. This has been worked around by having third party package managers. They are not really a solution for end user deployment, because you can't tell them to install a package manager just to use your app. On these platforms you must produce self-contained applications.
The traditional approach to this has been to bundle dependencies inside your own project. Either as prebuilt libraries and headers or by embedding the source code inside your source tree and rewriting your build system to build them as part of your project.
This is both tedious and error prone because it is always done by hand. The Wrap dependency system of Meson aims to provide an automated way to do this.
One of the major problems of multiplatform development is wrangling
all your dependencies. This is easy on Linux where you can use system
packages but awkward on other platforms. Most of those do not have a
package manager at all. This has been worked around by having third
party package managers. They are not really a solution for end user
deployment, because you can't tell them to install a package manager
just to use your app. On these platforms you must produce
self-contained applications.
The traditional approach to this has been to bundle dependencies
inside your own project. Either as prebuilt libraries and headers or
by embedding the source code inside your source tree and rewriting
your build system to build them as part of your project.
This is both tedious and error prone because it is always done by
hand. The Wrap dependency system of Meson aims to provide an automated
way to do this.
## How it works
Meson has a concept of [subprojects](Subprojects.md). They are a way of nesting one Meson project inside another. Any project that builds with Meson can detect that it is built as a subproject and build itself in a way that makes it easy to use (usually this means as a static library).
Meson has a concept of [subprojects](Subprojects.md). They are a way
of nesting one Meson project inside another. Any project that builds
with Meson can detect that it is built as a subproject and build
itself in a way that makes it easy to use (usually this means as a
static library).
To use this kind of a project as a dependency you could just copy and extract it inside your project's `subprojects` directory. However there is a simpler way. You can specify a Wrap file that tells Meson how to download it for you. An example wrap file would look like this and should be put in `subprojects/foobar.wrap`:
To use this kind of a project as a dependency you could just copy and
extract it inside your project's `subprojects` directory. However
there is a simpler way. You can specify a Wrap file that tells Meson
how to download it for you. An example wrap file would look like this
and should be put in `subprojects/foobar.wrap`:
```ini
[wrap-file]
@ -21,9 +41,16 @@ source_filename = foobar-1.0.tar.gz
source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663
```
If you then use this subproject in your build, Meson will automatically download and extract it during build. This makes subproject embedding extremely easy.
If you then use this subproject in your build, Meson will
automatically download and extract it during build. This makes
subproject embedding extremely easy.
Unfortunately most software projects in the world do not build with Meson. Because of this Meson allows you to specify a patch URL. This works in much the same way as Debian's distro patches. That is, they are downloaded and automatically applied to the subproject. These files contain a Meson build definition for the given subproject. A wrap file with an additional patch URL would look like this.
Unfortunately most software projects in the world do not build with
Meson. Because of this Meson allows you to specify a patch URL. This
works in much the same way as Debian's distro patches. That is, they
are downloaded and automatically applied to the subproject. These
files contain a Meson build definition for the given subproject. A
wrap file with an additional patch URL would look like this.
```
[wrap-file]
@ -38,13 +65,23 @@ patch_filename = libfoobar-meson.tar.gz
patch_hash = 8c9d00702d5fe4a6bf25a36b821a332f6b2dfd117c66fe818b88b23d604635e9
```
In this example the Wrap manager would download the patch and unzip it in libfoobar's directory.
In this example the Wrap manager would download the patch and unzip it
in libfoobar's directory.
This approach makes it extremely simple to embed dependencies that require build system changes. You can write the Meson build definition for the dependency in total isolation. This is a lot better than doing it inside your own source tree, especially if it contains hundreds of thousands of lines of code. Once you have a working build definition, just zip up the Meson build files (and others you have changed) and put them somewhere where you can download them.
This approach makes it extremely simple to embed dependencies that
require build system changes. You can write the Meson build definition
for the dependency in total isolation. This is a lot better than doing
it inside your own source tree, especially if it contains hundreds of
thousands of lines of code. Once you have a working build definition,
just zip up the Meson build files (and others you have changed) and
put them somewhere where you can download them.
## Branching subprojects directly from git
The above mentioned scheme assumes that your subproject is working off packaged files. Sometimes you want to check code out directly from Git. Meson supports this natively. All you need to do is to write a slightly different wrap file.
The above mentioned scheme assumes that your subproject is working off
packaged files. Sometimes you want to check code out directly from
Git. Meson supports this natively. All you need to do is to write a
slightly different wrap file.
```
[wrap-git]
@ -53,11 +90,20 @@ url=https://github.com/jpakkane/samplesubproject.git
revision=head
```
The format is straightforward. The only thing to note is the revision element that can have one of two values. The first is `head` which will cause Meson to track the master head (doing a repull whenever the build definition is altered). The second type is a commit hash. In this case Meson will use the commit specified (with `git checkout [hash id]`).
The format is straightforward. The only thing to note is the revision
element that can have one of two values. The first is `head` which
will cause Meson to track the master head (doing a repull whenever the
build definition is altered). The second type is a commit hash. In
this case Meson will use the commit specified (with `git checkout
[hash id]`).
Note that in this case you cannot specify an extra patch file to use. The git repo must contain all necessary Meson build definitions.
Note that in this case you cannot specify an extra patch file to
use. The git repo must contain all necessary Meson build definitions.
Usually you would use subprojects as read only. However in some cases you want to do commits to subprojects and push them upstream. For these cases you can specify the upload URL by adding the following at the end of your wrap file:
Usually you would use subprojects as read only. However in some cases
you want to do commits to subprojects and push them upstream. For
these cases you can specify the upload URL by adding the following at
the end of your wrap file:
```ini
push-url=git@git.example.com:projects/someproject.git # Supported since version 0.37.0
@ -71,7 +117,9 @@ To use a subproject simply do this in your top level `meson.build`.
foobar_sp = subproject('foobar')
```
Usually dependencies consist of some header files plus a library to link against. To do this you would declare this internal dependency like this:
Usually dependencies consist of some header files plus a library to
link against. To do this you would declare this internal dependency
like this:
```meson
foobar_dep = declare_dependency(link_with : mylib,
@ -85,13 +133,21 @@ executable('toplevel_exe', 'prog.c',
dependencies : foobar_sp.get_variable('foobar_dep'))
```
Note that the subproject object is *not* used as the dependency, but rather you need to get the declared dependency from it with `get_variable` because a subproject may have multiple declared dependencies.
Note that the subproject object is *not* used as the dependency, but
rather you need to get the declared dependency from it with
`get_variable` because a subproject may have multiple declared
dependencies.
## Toggling between distro packages and embedded source
When building distro packages it is very important that you do not embed any sources. Some distros have a rule forbidding embedded dependencies so your project must be buildable without them or otherwise the packager will hate you.
When building distro packages it is very important that you do not
embed any sources. Some distros have a rule forbidding embedded
dependencies so your project must be buildable without them or
otherwise the packager will hate you.
Doing this with Meson and Wrap is simple. Here's how you would use distro packages and fall back to embedding if the dependency is not available.
Doing this with Meson and Wrap is simple. Here's how you would use
distro packages and fall back to embedding if the dependency is not
available.
```meson
foobar_dep = dependency('foobar', required : false)
@ -107,16 +163,27 @@ executable('toplevel_exe', 'prog.c',
dependencies : foobar_dep)
```
Because this is such a common operation, Meson provides a shortcut for this use case.
Because this is such a common operation, Meson provides a shortcut for
this use case.
```meson
foobar_dep = dependency('foobar', fallback : ['foobar', 'foobar_dep'])
```
The `fallback` keyword argument takes two items, the name of the subproject and the name of the variable that holds the dependency. If you need to do something more complicated, such as extract several different variables, then you need to do it yourself with the manual method described above.
The `fallback` keyword argument takes two items, the name of the
subproject and the name of the variable that holds the dependency. If
you need to do something more complicated, such as extract several
different variables, then you need to do it yourself with the manual
method described above.
With this setup when foobar is provided by the system, we use it. When that is not the case we use the embedded version. Note that `foobar_dep` can point to an external or an internal dependency but you don't have to worry about their differences. Meson will take care of the details for you.
With this setup when foobar is provided by the system, we use it. When
that is not the case we use the embedded version. Note that
`foobar_dep` can point to an external or an internal dependency but
you don't have to worry about their differences. Meson will take care
of the details for you.
## Getting wraps
Usually you don't want to write your wraps by hand. There is an online repository called [WrapDB](Using-the-WrapDB.md) that provides many dependencies ready to use.
Usually you don't want to write your wraps by hand. There is an online
repository called [WrapDB](Using-the-WrapDB.md) that provides many
dependencies ready to use.

7
docs/markdown/Wrap-review-guidelines.md
Unescape View File

@ -1,6 +1,11 @@
# Wrap review guidelines
In order to get a package in the Wrap database it must be reviewed and accepted by someone with admin rights. Here is a list of items to check in the review. If some item is not met it does not mean that the package is rejected. What should be done will be determined on a case-by-case basis. Similarly meeting all these requirements does not guarantee that the package will get accepted. Use common sense.
In order to get a package in the Wrap database it must be reviewed and
accepted by someone with admin rights. Here is a list of items to
check in the review. If some item is not met it does not mean that the
package is rejected. What should be done will be determined on a
case-by-case basis. Similarly meeting all these requirements does not
guarantee that the package will get accepted. Use common sense.
## Checklist ##

36
docs/markdown/i18n-module.md
Unescape View File

@ -4,16 +4,33 @@ This module provides internationalisation and localisation functionality.
## Usage
To use this module, just do: **`i18n = import('i18n')`**. The following functions will then be available as methods on the object with the name `i18n`. You can, of course, replace the name `i18n` with anything else.
To use this module, just do: **`i18n = import('i18n')`**. The
following functions will then be available as methods on the object
with the name `i18n`. You can, of course, replace the name `i18n` with
anything else.
### i18n.gettext()
Sets up gettext localisation so that translations are built and placed into their proper locations during install. Takes one positional argument which is the name of the gettext module.
Sets up gettext localisation so that translations are built and placed
into their proper locations during install. Takes one positional
argument which is the name of the gettext module.
* `languages`: list of languages that are to be generated. As of 0.37.0 this is optional and the [LINGUAS](https://www.gnu.org/software/gettext/manual/html_node/po_002fLINGUAS.html) file is read.
* `data_dirs`: (*Added 0.36.0*) list of directories to be set for `GETTEXTDATADIRS` env var (Requires gettext 0.19.8+), used for local its files
* `preset`: (*Added 0.37.0*) name of a preset list of arguments, current option is `'glib'`, see [source](https://github.com/mesonbuild/meson/blob/master/mesonbuild/modules/i18n.py) for for their value
* `args`: list of extra arguments to pass to `xgettext` when generating the pot file
* `args`: list of extra arguments to pass to `xgettext` when
generating the pot file
* `data_dirs`: (*Added 0.36.0*) list of directories to be set for
`GETTEXTDATADIRS` env var (Requires gettext 0.19.8+), used for local
its files
* `languages`: list of languages that are to be generated. As of
0.37.0 this is optional and the
[LINGUAS](https://www.gnu.org/software/gettext/manual/html_node/po_002fLINGUAS.html)
file is read.
* `preset`: (*Added 0.37.0*) name of a preset list of arguments,
current option is `'glib'`, see
[source](https://github.com/mesonbuild/meson/blob/master/mesonbuild/modules/i18n.py)
for for their value
This function also defines targets for maintainers to use:
**Note**: These output to the source directory
@ -24,10 +41,13 @@ This function also defines targets for maintainers to use:
### i18n.merge_file()
This merges translations into a text file using `msgfmt`. See [custom_target](https://github.com/mesonbuild/meson/wiki/Reference%20manual#custom_target) for normal keywords. In addition it accepts these keywords:
This merges translations into a text file using `msgfmt`. See
[custom_target](https://github.com/mesonbuild/meson/wiki/Reference%20manual#custom_target)
for normal keywords. In addition it accepts these keywords:
* `data_dirs`: (*Added 0.41.0*) list of directories for its files (See
also `i18n.gettext()`)
* `po_dir`: directory containing translations, relative to current directory
* `data_dirs`: (*Added 0.41.0*) list of directories for its files (See also `i18n.gettext()`)
* `type`: type of file, valid options are `'xml'` (default) and `'desktop'`
*Added 0.37.0*

Write Preview
Loading…
Cancel
Save