diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Adding-new-projects-to-wrapdb.md | 110 | ||||
| -rw-r--r-- | docs/markdown/Getting-meson.md | 9 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 6 | ||||
| -rw-r--r-- | docs/markdown/Tutorial.md | 50 | ||||
| -rw-r--r-- | docs/markdown/snippets/keys_of_configuration_data.md | 4 |
5 files changed, 124 insertions, 55 deletions
diff --git a/docs/markdown/Adding-new-projects-to-wrapdb.md b/docs/markdown/Adding-new-projects-to-wrapdb.md index a266379..5bdadfa 100644 --- a/docs/markdown/Adding-new-projects-to-wrapdb.md +++ b/docs/markdown/Adding-new-projects-to-wrapdb.md @@ -3,29 +3,34 @@ ## How it works -Each wrap repository has a master branch with only one initial commit and *no* wrap files. -And that is the only commit ever made on that branch. - -For every release of a project a new branch is created. The new branch is named after the -the upstream release number (e.g. `1.0.0`). This branch holds a wrap file for -this particular release. - -There are two types of wraps on WrapDB - regular wraps and wraps with Meson build -definition patches. A wrap file in a repository on WrapDB must have a name `upstream.wrap`. - -Wraps with Meson build definition patches work in much the same way as Debian: -we take the unaltered upstream source package and add a new build system to it as a patch. -These build systems are stored as Git repositories on GitHub. They only contain build definition files. -You may also think of them as an overlay to upstream source. - -Whenever a new commit is pushed into GitHub's project branch, a new wrap is generated -with an incremented version number. All the old releases remain unaltered. -New commits are always done via GitHub merge requests and must be reviewed by -someone other than the submitter. - -Note that your Git repo with wrap must not contain the subdirectory of the source -release. That gets added automatically by the service. You also must not commit -any source code from the original tarball into the wrap repository. +Each wrap repository has a master branch with only one initial commit +and *no* wrap files. And that is the only commit ever made on that +branch. + +For every release of a project a new branch is created. The new branch +is named after the the upstream release number (e.g. `1.0.0`). This +branch holds a wrap file for this particular release. + +There are two types of wraps on WrapDB - regular wraps and wraps with +Meson build definition patches. A wrap file in a repository on WrapDB +must have a name `upstream.wrap`. + +Wraps with Meson build definition patches work in much the same way as +Debian: we take the unaltered upstream source package and add a new +build system to it as a patch. These build systems are stored as Git +repositories on GitHub. They only contain build definition files. You +may also think of them as an overlay to upstream source. + +Whenever a new commit is pushed into GitHub's project branch, a new +wrap is generated with an incremented version number. All the old +releases remain unaltered. New commits are always done via GitHub +merge requests and must be reviewed by someone other than the +submitter. + +Note that your Git repo with wrap must not contain the subdirectory of +the source release. That gets added automatically by the service. You +also must not commit any source code from the original tarball into +the wrap repository. ## Choosing the repository name @@ -34,29 +39,32 @@ they should have the same name as the upstream projects. NOTE: Repo names must fully match this regexp: `[a-z0-9._]+`. -If the project provides a pkg-config file, then the repository name should be -the same as the pkg-config name. Usually this is the name of the -project, such as `libpng`. Sometimes it is slightly different, +If the project provides a pkg-config file, then the repository name +should be the same as the pkg-config name. Usually this is the name of +the project, such as `libpng`. Sometimes it is slightly different, however. As an example the libogg project's chosen pkg-config name is `ogg` instead of `libogg`, which is the reason why the repository is named plain `ogg`. -If there is no a pkg-config file, the name the project uses/promotes should be used, -lowercase only (Catch2 -> catch2). +If there is no a pkg-config file, the name the project uses/promotes +should be used, lowercase only (Catch2 -> catch2). If the project name is too generic or ambiguous (e.g. `benchmark`), -consider using `organization-project` naming format (e.g. `google-benchmark`). +consider using `organization-project` naming format (e.g. +`google-benchmark`). ## How to contribute a new wrap -If the project already uses Meson build system, then only a wrap file - `upstream.wrap` -should be provided. In other case a Meson build definition patch - a set of `meson.build` -files - should be also provided. +If the project already uses Meson build system, then only a wrap file +- `upstream.wrap` should be provided. In other case a Meson build +definition patch - a set of `meson.build` files - should be also +provided. ### Request a new repository -Create an issue on the [wrapdb bug tracker](https://github.com/mesonbuild/wrapdb/issues) -using *Title* and *Description* below as a template. +Create an issue on the [wrapdb bug +tracker](https://github.com/mesonbuild/wrapdb/issues) using *Title* +and *Description* below as a template. *Title:* `new wrap: <project_name>` @@ -66,17 +74,18 @@ upstream url: <link_to_updastream> version: <version_you_have_a_wrap_for> ``` -Wait until the new repository or branch is created. A link to the new repository or branch -will be posted in a comment to this issue. +Wait until the new repository or branch is created. A link to the new +repository or branch will be posted in a comment to this issue. -NOTE: Requesting a branch is not necessary. WrapDB maintainer can create the branch and -modify the PR accordingly if the project repository exists. +NOTE: Requesting a branch is not necessary. WrapDB maintainer can +create the branch and modify the PR accordingly if the project +repository exists. ### Creating the wrap contents -Setting up the contents might seem a bit counterintuitive at -first. Just remember that the outcome needs to have one (and only one) -commit that has all the build definition files (i.e. `meson.build` and +Setting up the contents might seem a bit counterintuitive at first. +Just remember that the outcome needs to have one (and only one) commit +that has all the build definition files (i.e. `meson.build` and `meson_options.txt` files) and _nothing else_. It is good practice to have this commit in a branch whose name matches the release as described above. @@ -132,6 +141,25 @@ Under macOS the command is the following: shasum -a 256 path/to/libfoo-1.0.0.tar.gz ``` +Next you need to add the entries that define what dependencies the +current project provides. This is important, as it is what makes +Meson's automatic dependency resolver work. It is done by adding a +`provide` entry at the end of the `upstream.wrap` file. Using the Ogg +library as an example, this is what it would look like: + +```ini +[provide] +ogg = ogg_dep +``` + +The `ogg` part on the left refers to the dependency name, which should +be the same as its Pkg-Config name. `ogg_dep` on the right refers to +the variable in the build definitions that provides the dependency. +Most commonly it holds the result of a `declare_dependency` call. If a +variable of that name is not defined, Meson will exit with a hard +error. For further details see [the main Wrap +manual](Wrap-dependency-system-manual.md). + Now you can create the build files and work on them until the project builds correctly. diff --git a/docs/markdown/Getting-meson.md b/docs/markdown/Getting-meson.md index e0e5722..3568dfc 100644 --- a/docs/markdown/Getting-meson.md +++ b/docs/markdown/Getting-meson.md @@ -23,12 +23,17 @@ a pull-request process that runs CI and tests several platforms. ## Installing Meson with pip Meson is available in the [Python Package Index] and can be installed with -`pip3 install meson` which requires root and will install it system-wide. +`sudo pip3 install meson` which requires root and will install it system-wide. + +If you have downloaded a copy of the meson sources already, you can install it +with `sudo pip3 install path/to/source/root/`. Alternatively, you can use `pip3 install --user meson` which will install it for your user and does not require any special privileges. This will install the package in `~/.local/`, so you will have to add `~/.local/bin` to your -`PATH`. +`PATH`, and `sudo meson install` will be completely broken since the +program will not be available to root. Only use a user copy of meson if you +do not care about installing projects as root. ## Installing Meson and Ninja with the MSI installer diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 3af78ef..aeaeccb 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -2409,6 +2409,12 @@ page](Configuration.md) It has three methods: - `has(varname)`: returns `true` if the specified variable is set +- `keys()`*(since 0.57.0)*: returns an array of keys of + the configuration data object. + + You can iterate over this array with the [`foreach` + statement](Syntax.md#foreach-statements). + - `merge_from(other)` *(since 0.42.0)*: takes as argument a different configuration data object and copies all entries from that object to the current. diff --git a/docs/markdown/Tutorial.md b/docs/markdown/Tutorial.md index bf337ba..85e345a 100644 --- a/docs/markdown/Tutorial.md +++ b/docs/markdown/Tutorial.md @@ -29,8 +29,11 @@ example. First we create a file `main.c` which holds the source. It looks like this. ```c -#include<stdio.h> +#include <stdio.h> +// +// main is where all program execution starts +// int main(int argc, char **argv) { printf("Hello there.\n"); return 0; @@ -53,7 +56,7 @@ to initialize the build by going into the source directory and issuing the following commands. ```console -$ meson builddir +$ meson setup builddir ``` We create a separate build directory to hold all of the compiler @@ -110,17 +113,40 @@ create a graphical window instead. We'll use the use GTK+. The new version looks like this. ```c -#include<gtk/gtk.h> -int main(int argc, char **argv) { - GtkWidget *win; - gtk_init(&argc, &argv); - win = gtk_window_new(GTK_WINDOW_TOPLEVEL); - gtk_window_set_title(GTK_WINDOW(win), "Hello there"); - g_signal_connect(win, "destroy", G_CALLBACK(gtk_main_quit), NULL); - gtk_widget_show(win); - gtk_main(); -} +#include <gtk/gtk.h> + +// +// Should provided the active view for a GTK application +// +static void activate(GtkApplication* app, gpointer user_data) +{ + GtkWidget *window; + GtkWidget *label; + + window = gtk_application_window_new (app); + label = gtk_label_new("Hello GNOME!"); + gtk_container_add (GTK_CONTAINER (window), label); + gtk_window_set_title(GTK_WINDOW (window), "Welcome to GNOME"); + gtk_window_set_default_size(GTK_WINDOW (window), 200, 100); + gtk_widget_show_all(window); +} // end of function activate + +// +// main is where all program execution starts +// +int main(int argc, char **argv) +{ + GtkApplication *app; + int status; + + app = gtk_application_new(NULL, G_APPLICATION_FLAGS_NONE); + g_signal_connect(app, "activate", G_CALLBACK(activate), NULL); + status = g_application_run(G_APPLICATION(app), argc, argv); + g_object_unref(app); + + return status; +} // end of function main ``` Then we edit the Meson file, instructing it to find and use the GTK+ diff --git a/docs/markdown/snippets/keys_of_configuration_data.md b/docs/markdown/snippets/keys_of_configuration_data.md new file mode 100644 index 0000000..c0cbfc2 --- /dev/null +++ b/docs/markdown/snippets/keys_of_configuration_data.md @@ -0,0 +1,4 @@ +## Get keys of configuration data object + +All keys of the `configuration_data` object can be obtained with the `keys()` +method as an alphabetically sorted array. |