From abf99f533f57132652b77f0def13b57670f67e78 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 9 Oct 2023 23:38:18 +0100 Subject: [PATCH] docs: Move compiling documentation to Markdown Helps: #3037 --- docs/reference/glib/compiling.md | 71 +++++++++++++++++ docs/reference/glib/compiling.xml | 125 ------------------------------ docs/reference/glib/glib-docs.xml | 1 - docs/reference/glib/glib.toml.in | 1 + docs/reference/glib/meson.build | 3 +- 5 files changed, 73 insertions(+), 128 deletions(-) create mode 100644 docs/reference/glib/compiling.md delete mode 100644 docs/reference/glib/compiling.xml diff --git a/docs/reference/glib/compiling.md b/docs/reference/glib/compiling.md new file mode 100644 index 000000000..38f151787 --- /dev/null +++ b/docs/reference/glib/compiling.md @@ -0,0 +1,71 @@ +Title: Compiling GLib Applications + +# Compiling GLib Applications + +To compile a GLib application, you need to tell the compiler where to find +the GLib header files and libraries. This is done with the +[`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) +utility. + +The following interactive shell session demonstrates how pkg-config is used +(the actual output on your system may be different): + + $ pkg-config --cflags glib-2.0 + -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include + $ pkg-config --libs glib-2.0 + -L/usr/lib -lm -lglib-2.0 + +See the `pkg-config` website for more information about `pkg-config`. + +If your application uses or GObject features, it must be compiled and linked +with the options returned by the following `pkg-config` invocation: + + $ pkg-config --cflags --libs gobject-2.0 + +If your application uses modules, it must be compiled and linked with the +options returned by one of the following pkg-config invocations: + + $ pkg-config --cflags --libs gmodule-no-export-2.0 + $ pkg-config --cflags --libs gmodule-2.0 + +The difference between the two is that `gmodule-2.0` adds `--export-dynamic` +to the linker flags, which is often not needed. + +The simplest way to compile a program is to use the "backticks" feature of +the shell. If you enclose a command in backticks (not single quotes), then +its output will be substituted into the command line before execution. So to +compile a GLib Hello, World, you would type the following: + + $ cc `pkg-config --cflags glib-2.0` hello.c -o hello `pkg-config --libs glib-2.0` + +Deprecated GLib functions are annotated to make the compiler emit warnings +when they are used (e.g. with GCC, you need to use the +`-Wdeprecated-declarations option`). If these warnings are problematic, they +can be turned off by defining the preprocessor symbol +`GLIB_DISABLE_DEPRECATION_WARNINGS` by using the commandline option +`-DGLIB_DISABLE_DEPRECATION_WARNINGS` + +GLib deprecation annotations are versioned; by defining the macros +`GLIB_VERSION_MIN_REQUIRED` and `GLIB_VERSION_MAX_ALLOWED`, you can specify the +range of GLib versions whose API you want to use. APIs that were deprecated +before or introduced after this range will trigger compiler warnings. + +Since GLib 2.62, the older deprecation mechanism of hiding deprecated +interfaces entirely from the compiler by using the preprocessor symbol +`G_DISABLE_DEPRECATED` has been removed. All deprecations are now handled +using the above mechanism. + +The recommended way of using GLib has always been to only include the +toplevel headers `glib.h`, `glib-object.h`, `gio.h`. Starting with 2.32, GLib +enforces this by generating an error when individual headers are directly +included. + +Still, there are some exceptions; these headers have to be included +separately: + +- `gmodule.h` +- `glib-unix.h` +- `glib/gi18n-lib.h` or `glib/gi18n.h` (see the section on + [Internationalization](i18n.html)) +- `glib/gprintf.h` and `glib/gstdio.h` (we don't want to pull in all of + stdio) diff --git a/docs/reference/glib/compiling.xml b/docs/reference/glib/compiling.xml deleted file mode 100644 index c7a058c5f..000000000 --- a/docs/reference/glib/compiling.xml +++ /dev/null @@ -1,125 +0,0 @@ - - - - -Compiling GLib Applications -3 -GLib Library - - - -Compiling GLib Applications - -How to compile your GLib application - - - - -Compiling GLib Applications on UNIX - - -To compile a GLib application, you need to tell the compiler where to -find the GLib header files and libraries. This is done with the -pkg-config utility. - - -The following interactive shell session demonstrates how -pkg-config is used (the actual output on -your system may be different): - -$ pkg-config --cflags glib-2.0 - -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -$ pkg-config --libs glib-2.0 - -L/usr/lib -lm -lglib-2.0 - - - -See the pkg-config website -for more information about pkg-config. - - -If your application uses or GObject -features, it must be compiled and linked with the options returned -by the following pkg-config invocation: - -$ pkg-config --cflags --libs gobject-2.0 - - - -If your application uses modules, it must be compiled and linked -with the options returned by one of the following -pkg-config invocations: - -$ pkg-config --cflags --libs gmodule-no-export-2.0 -$ pkg-config --cflags --libs gmodule-2.0 - -The difference between the two is that gmodule-2.0 adds - to the linker flags, -which is often not needed. - - -The simplest way to compile a program is to use command substitution -feature of a shell. A command written in the format -$(command) gets substituted into the command line -before execution. So to compile a GLib Hello, World, you would type -the following: - -$ cc hello.c $(pkg-config --cflags --libs glib-2.0) -o hello - - - -Note that the name of the file must come before the other options -(such as pkg-config), or else you may get an -error from the linker. - - - -Deprecated GLib functions are annotated to make the compiler -emit warnings when they are used (e.g. with gcc, you need to use -the -Wdeprecated-declarations option). If these warnings are -problematic, they can be turned off by defining the preprocessor -symbol %GLIB_DISABLE_DEPRECATION_WARNINGS by using the commandline -option -DGLIB_DISABLE_DEPRECATION_WARNINGS - - - -GLib deprecation annotations are versioned; by defining the -macros %GLIB_VERSION_MIN_REQUIRED and %GLIB_VERSION_MAX_ALLOWED, -you can specify the range of GLib versions whose API you want -to use. APIs that were deprecated before or introduced after -this range will trigger compiler warnings. - - - -Since GLib 2.62, the older deprecation mechanism of hiding deprecated interfaces -entirely from the compiler by using the preprocessor symbol -G_DISABLE_DEPRECATED has been removed. All deprecations -are now handled using the above mechanism. - - - -The recommended way of using GLib has always been to only include the -toplevel headers glib.h, -glib-object.h, gio.h. -Starting with 2.32, GLib enforces this by generating an error -when individual headers are directly included. - - - -Still, there are some exceptions; these headers have to be included -separately: -gmodule.h, -glib-unix.h, -glib/gi18n-lib.h or -glib/gi18n.h (see -the Internationalization section), -glib/gprintf.h and -glib/gstdio.h -(we don't want to pull in all of stdio). - - - - - diff --git a/docs/reference/glib/glib-docs.xml b/docs/reference/glib/glib-docs.xml index 54314de12..ae86deb52 100644 --- a/docs/reference/glib/glib-docs.xml +++ b/docs/reference/glib/glib-docs.xml @@ -26,7 +26,6 @@ - diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 2f489bd1d..c333baebd 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -40,6 +40,7 @@ show_class_hierarchy = true urlmap_file = "urlmap.js" # The same order will be used when generating the index content_files = [ + "compiling.md", "cross-compiling.md", "running.md", diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index 5e82ad5a9..d2b682d7c 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -73,7 +73,6 @@ if get_option('gtk_doc') content_files : [ 'building.xml', 'changes.xml', - 'compiling.xml', 'programming.xml', 'resources.xml', 'regex-syntax.xml', @@ -82,7 +81,6 @@ if get_option('gtk_doc') 'gtester-report.xml', ], expand_content_files : [ - 'compiling.xml', ], html_assets : [ 'file-name-encodings.png', @@ -149,6 +147,7 @@ endif # gi-docgen version expand_content_files = [ 'character-set.md', + 'compiling.md', 'cross-compiling.md', 'error-reporting.md', 'gvariant-format-strings.md',