openharmony/third_party_glib
1
0
Fork 0
mirror of https://github.com/openharmony/third_party_glib.git synced 2026-07-01 04:35:39 -04:00
Code Issues Packages Projects Releases Wiki Activity

update OpenHarmony 2.0 Canary

Browse Source
This commit is contained in:
mamingshuai
2021-06-02 00:29:26 +08:00
parent 11442ad3f5
commit a1364de9be
1950 changed files with 1289051 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.dir-locals.el
+1
View File
@@ -0,0 +1 @@
((c-mode . ((indent-tabs-mode . nil)))))
.gitattributes
+1
View File
@@ -0,0 +1 @@
README.win32 text eol=crlf
.gitignore
+30
View File
@@ -0,0 +1,30 @@
# for all subdirectories
TAGS
tags
.libs
.deps
*.o
*.lo
*.la
*.pc
.*.swp
.sw?
*.rc
*.gcno
*.gcda
*.gcov
*.sourcefiles
*.stp
*.exe
*.def
*.test
*.log
*.trs
INSTALL
/glib-lcov.info
/glib-lcov/
# Meson
/meson-build/
/subprojects/*/
.gitlab-ci.yml
+355
View File
@@ -0,0 +1,355 @@
stages:
- build
- coverage
- analysis
- deploy
cache:
paths:
- _ccache/
variables:
MESON_TEST_TIMEOUT_MULTIPLIER: 2
G_MESSAGES_DEBUG: all
MESON_COMMON_OPTIONS: "--buildtype debug --fatal-meson-warnings"
fedora-x86_64:
image: registry.gitlab.gnome.org/gnome/glib/fedora:v3
stage: build
except:
- tags
variables:
CFLAGS: "-coverage -ftest-coverage -fprofile-arcs"
script:
- meson ${MESON_COMMON_OPTIONS}
--werror
--default-library=both
--prefix=$HOME/glib-installed
--libdir=lib
-Dsystemtap=true
-Ddtrace=true
-Dfam=true
-Dinstalled_tests=true
_build
- ninja -C _build
- mkdir -p _coverage
- lcov --config-file .gitlab-ci/lcovrc --directory _build --capture --initial --output-file "_coverage/${CI_JOB_NAME}-baseline.lcov"
- .gitlab-ci/run-tests.sh
- lcov --config-file .gitlab-ci/lcovrc --directory _build --capture --output-file "_coverage/${CI_JOB_NAME}.lcov"
# FIXME: We should run all installed tests, but do only this one for now
# because it cannot run uninstalled. Reconfigure with dtrace disabled
# because it breaks static link.
- meson configure -Ddtrace=false _build
- ninja -C _build install
- GLIB_TEST_COMPILATION=1 $HOME/glib-installed/libexec/installed-tests/glib/static-link.py $HOME/glib-installed/lib/pkgconfig
artifacts:
reports:
junit: "_build/${CI_JOB_NAME}-report.xml"
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
- "_build/${CI_JOB_NAME}-report.xml"
- "_coverage"
debian-stable-x86_64:
image: registry.gitlab.gnome.org/gnome/glib/debian-stable:v3
stage: build
except:
- tags
script:
- meson ${MESON_COMMON_OPTIONS}
--werror
--default-library=both
--prefix=$HOME/glib-installed
--libdir=lib
-Dsystemtap=true
-Ddtrace=true
-Dfam=true
-Dinstalled_tests=true
_build
- ninja -C _build
- .gitlab-ci/run-tests.sh
artifacts:
reports:
junit: "_build/${CI_JOB_NAME}-report.xml"
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
- "_build/${CI_JOB_NAME}-report.xml"
G_DISABLE_ASSERT:
image: registry.gitlab.gnome.org/gnome/glib/fedora:v3
stage: build
except:
- tags
variables:
CPPFLAGS: "-DG_DISABLE_ASSERT"
script:
- meson ${MESON_COMMON_OPTIONS}
--werror
-Dsystemtap=true
-Ddtrace=true
-Dfam=true
-Dinstalled_tests=true
_build
- ninja -C _build
- bash -x ./.gitlab-ci/run-tests.sh
artifacts:
reports:
junit: "_build/${CI_JOB_NAME}-report.xml"
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
- "_build/${CI_JOB_NAME}-report.xml"
valgrind:
image: registry.gitlab.gnome.org/gnome/glib/fedora:v3
stage: analysis
except:
- tags
variables:
MESON_TEST_TIMEOUT_MULTIPLIER: 10
script:
- meson ${MESON_COMMON_OPTIONS}
--werror
-Dsystemtap=true
-Ddtrace=true
-Dfam=true
-Dinstalled_tests=true
_build
- ninja -C _build
- bash -x ./.gitlab-ci/run-tests.sh
--log-file _build/meson-logs/testlog-valgrind.json
--wrap "valgrind --tool=memcheck --error-exitcode=1 --track-origins=yes --leak-check=full --leak-resolution=high --num-callers=50 --show-leak-kinds=definite,possible --show-error-list=yes --suppressions=${CI_PROJECT_DIR}/glib.supp"
--no-suite no-valgrind
--no-suite slow
# FIXME: Remove this when we have zero valgrind leaks.
# https://gitlab.gnome.org/GNOME/glib/issues/333
allow_failure: true
artifacts:
reports:
junit: "_build/${CI_JOB_NAME}-report.xml"
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
.cross-template: &cross-template
stage: build
except:
- tags
artifacts:
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
paths:
- "_build/meson-logs"
cross-android_api21_arm64:
<<: *cross-template
image: registry.gitlab.gnome.org/gnome/glib/android-ndk:v1
script:
# FIXME: add --werror
# We use -Diconv=auto to test that we successfully detect that iconv is not
# provided by android api 21, and detect the external iconv instead.
- meson ${MESON_COMMON_OPTIONS} --cross-file=/opt/cross_file_android_arm64_21.txt -Diconv=auto -Dinternal_pcre=true _build
- ninja -C _build
cross-android_api28_arm64:
<<: *cross-template
image: registry.gitlab.gnome.org/gnome/glib/android-ndk:v1
script:
# FIXME: add --werror
- meson ${MESON_COMMON_OPTIONS} --cross-file=/opt/cross_file_android_arm64_28.txt -Dinternal_pcre=true _build
- ninja -C _build
cross-mingw64:
<<: *cross-template
image: registry.gitlab.gnome.org/gnome/glib/mingw:v1
script:
# FIXME: Add --werror
- meson ${MESON_COMMON_OPTIONS} --cross-file=/opt/cross_file_mingw64.txt _build
- ninja -C _build
msys2-mingw32:
stage: build
except:
- tags
tags:
- win32
variables:
MSYSTEM: "MINGW32"
CHERE_INVOKING: "yes"
script:
- C:\msys64\usr\bin\pacman --noconfirm -Syyuu --ask 20
- C:\msys64\usr\bin\bash -lc "bash -x ./.gitlab-ci/test-msys2.sh"
artifacts:
reports:
junit: "_build/%CI_JOB_NAME%-report.xml"
name: "glib-%CI_JOB_NAME%-%CI_COMMIT_REF_NAME%"
when: always
paths:
- _build/meson-logs
- "_build/%CI_JOB_NAME%-report.xml"
- _coverage/
vs2017-x64:
stage: build
except:
- tags
tags:
- win32
script:
- .gitlab-ci/test-msvc.bat
artifacts:
reports:
junit: "_build/%CI_JOB_NAME%-report.xml"
name: "glib-%CI_JOB_NAME%-%CI_COMMIT_REF_NAME%"
when: always
paths:
- _build/meson-logs
- "_build/%CI_JOB_NAME%-report.xml"
freebsd-11-x86_64:
stage: build
only:
- branches@GNOME/glib
tags:
# To run a FreeBSD builder, install gitlab-runner package and start both
# gitlab-runner and dbus service because we need /var/lib/dbus/machine-id.
# To compile GLib, you still have to install the following packages:
# desktop-file-utils gettext libiconv meson pkgconf python3 shared-mime-info
- freebsd-11
variables:
# CPPFLAGS is required because libintl doesn't use pkg-config.
CPPFLAGS: -I/usr/local/include
# FIXME: Workaround meson inability to set LD_LIBRARY_PATH.
# https://github.com/mesonbuild/meson/issues/1383
# https://github.com/mesonbuild/meson/issues/1635
# https://github.com/mesonbuild/meson/issues/2881
LDFLAGS: -L/usr/local/lib -Wl,--disable-new-dtags
# FreeBSD doesn't have C.UTF-8 locale.
LANG: en_US.UTF-8
script:
# We cannot use -Wl,--no-undefined because GLib uses 'environ' variable.
# FreeBSD iconv doesn't handle transliteration, so we use (external) GNU libiconv here.
# FreeBSD supports xattr, but its API is different from Linux xattr.
# FIXME: extattr(2) support: https://gitlab.gnome.org/GNOME/glib/issues/1404
- meson ${MESON_COMMON_OPTIONS} -Db_lundef=false -Diconv=external -Dxattr=false _build
- ninja -C _build
- bash -x ./.gitlab-ci/run-tests.sh
except:
- tags
artifacts:
reports:
junit: "_build/${CI_JOB_NAME}-report.xml"
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
- "_build/${CI_JOB_NAME}-report.xml"
freebsd-12-x86_64:
stage: build
only:
- branches@GNOME/glib
tags:
- freebsd-12
variables:
CPPFLAGS: -I/usr/local/include
LDFLAGS: -L/usr/local/lib -Wl,--disable-new-dtags
LANG: en_US.UTF-8
script:
- meson ${MESON_COMMON_OPTIONS} -Db_lundef=false -Diconv=external -Dxattr=false _build
- ninja -C _build
- bash -x ./.gitlab-ci/run-tests.sh
except:
- tags
artifacts:
reports:
junit: "_build/${CI_JOB_NAME}-report.xml"
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
- "_build/${CI_JOB_NAME}-report.xml"
coverage:
image: registry.gitlab.gnome.org/gnome/glib/fedora:v3
stage: coverage
except:
- tags
artifacts:
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
paths:
- _coverage/
script:
- bash -x ./.gitlab-ci/coverage-docker.sh
coverage: '/^\s+lines\.+:\s+([\d.]+\%)\s+/'
scan-build:
image: registry.gitlab.gnome.org/gnome/glib/fedora:v3
stage: analysis
except:
- tags
script:
- meson ${MESON_COMMON_OPTIONS}
--werror
--default-library=both
--prefix=$HOME/glib-installed
--libdir=lib
-Dsystemtap=true
-Ddtrace=true
-Dfam=true
-Dinstalled_tests=true
_scan_build
- ninja -C _scan_build scan-build
artifacts:
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
paths:
- "_scan_build/meson-logs/scanbuild"
pages:
stage: deploy
only:
- master
script:
- mv _coverage/ public/
artifacts:
paths:
- public
dist-job:
image: registry.gitlab.gnome.org/gnome/glib/fedora:v3
stage: build
only:
- tags
script:
- meson --buildtype release --fatal-meson-warnings -Dgtk_doc=true -Dman=true _build
- cd _build
- ninja dist
- ninja glib-doc gobject-doc gio-doc
- tar -c -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/glib html
- tar -c -f "gobject-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/gobject html
- tar -c -f "gio-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/gio html
artifacts:
paths:
- "${CI_PROJECT_DIR}/_build/glib-docs.tar.xz"
- "${CI_PROJECT_DIR}/_build/gobject-docs.tar.xz"
- "${CI_PROJECT_DIR}/_build/gio-docs.tar.xz"
- "${CI_PROJECT_DIR}/_build/meson-dist/glib-*.tar.xz"
.gitlab-ci/README.md
+21
View File
@@ -0,0 +1,21 @@
# CI support stuff
## Docker image
GitLab CI jobs run in a Docker image, defined here. To update that image
(perhaps to install some more packages):
1. Edit `.gitlab-ci/Dockerfile` with the changes you want
1. Run `.gitlab-ci/run-docker.sh build --base=debian --base-version=1` to build
the new image (bump the version as needed)
1. Run `.gitlab-ci/run-docker.sh push --base=debian --base-version=1` to upload
the new image to the GNOME GitLab Docker registry
* If this is the first time you're doing this, you'll need to log into the
registry
* If you use 2-factor authentication on your GNOME GitLab account, you'll
need to [create a personal access token][pat] and use that rather than
your normal password
1. Edit `.gitlab-ci.yml` (in the root of this repository) to use your new
image
[pat]: https://gitlab.gnome.org/profile/personal_access_tokens
.gitlab-ci/android-download-ndk.sh
Executable
+31
View File
@@ -0,0 +1,31 @@
#!/bin/bash
#
# Copyright 2018 Collabora ltd.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, see <http://www.gnu.org/licenses/>.
#
# Author: Xavier Claessens <xavier.claessens@collabora.com>
#
set -e
# Download Android NDK
ANDROID_NDK_VERSION="r17b"
ANDROID_NDK_SHA512="062fac12f747730f5563995089a8b4abab683fbbc621aa8582fdf35fe327daee5d69ed2437af257c10ec4ef54ecd3805a8f134a1400eb8f34ee76f55c8dc9ae9"
wget --quiet https://dl.google.com/android/repository/android-ndk-$ANDROID_NDK_VERSION-linux-x86_64.zip
echo "$ANDROID_NDK_SHA512 android-ndk-$ANDROID_NDK_VERSION-linux-x86_64.zip" | sha512sum -c
unzip android-ndk-$ANDROID_NDK_VERSION-linux-x86_64.zip
rm android-ndk-$ANDROID_NDK_VERSION-linux-x86_64.zip
mv android-ndk-$ANDROID_NDK_VERSION $ANDROID_NDK_PATH
.gitlab-ci/android-ndk.Dockerfile
+75
View File
@@ -0,0 +1,75 @@
FROM fedora:28
RUN dnf -y install \
autoconf \
automake \
bindfs \
clang \
clang-analyzer \
desktop-file-utils \
elfutils-libelf-devel \
findutils \
fuse \
gamin-devel \
gcc \
gcc-c++ \
gettext \
git \
glibc-devel \
glibc-headers \
glibc-langpack-de \
glibc-langpack-el \
glibc-langpack-el \
glibc-langpack-en \
glibc-langpack-es \
glibc-langpack-es \
glibc-langpack-fa \
glibc-langpack-fr \
glibc-langpack-hr \
glibc-langpack-ja \
glibc-langpack-lt \
glibc-langpack-pl \
glibc-langpack-ru \
glibc-langpack-tr \
gtk-doc \
itstool \
lcov \
libattr-devel \
libffi-devel \
libmount-devel \
libselinux-devel \
libtool \
libxslt \
make \
ncurses-compat-libs \
ninja-build \
pcre-devel \
python3 \
python3-pip \
python3-wheel \
systemtap-sdt-devel \
unzip \
wget \
xz \
zlib-devel \
&& dnf clean all
WORKDIR /opt
ENV ANDROID_NDK_PATH /opt/android-ndk
COPY android-download-ndk.sh .
RUN ./android-download-ndk.sh
COPY android-setup-env.sh .
RUN ./android-setup-env.sh arm64 21
RUN ./android-setup-env.sh arm64 28
RUN rm -rf $ANDROID_NDK_PATH
RUN pip3 install meson==0.49.2
ARG HOST_USER_ID=5555
ENV HOST_USER_ID ${HOST_USER_ID}
RUN useradd -u $HOST_USER_ID -ms /bin/bash user
USER user
WORKDIR /home/user
ENV LANG C.UTF-8
.gitlab-ci/android-setup-env.sh
Executable
+100
View File
@@ -0,0 +1,100 @@
#!/bin/bash
#
# Copyright 2018 Collabora ltd.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, see <http://www.gnu.org/licenses/>.
#
# Author: Xavier Claessens <xavier.claessens@collabora.com>
#
set -e
arch=$1
api=$2
toolchain_path=$(pwd)/android-toolchain-$arch-$api
prefix_path=$(pwd)/android-$arch-$api
# Create standalone toolchains
$ANDROID_NDK_PATH/build/tools/make_standalone_toolchain.py --arch $arch --api $api --install-dir $toolchain_path
target_host=aarch64-linux-android
export AR=$target_host-ar
export AS=$target_host-clang
export CC=$target_host-clang
export CXX=$target_host-clang++
export LD=$target_host-ld
export STRIP=$target_host-strip
export PATH=$PATH:$toolchain_path/bin
# Cross build libiconv when using API level <= 28.
# Newer Android has it in its libc already.
if [ "$api" -lt "28" ]; then
wget --quiet http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.15.tar.gz
echo "1233fe3ca09341b53354fd4bfe342a7589181145a1232c9919583a8c9979636855839049f3406f253a9d9829908816bb71fd6d34dd544ba290d6f04251376b1a libiconv-1.15.tar.gz" | sha512sum -c
tar xzf libiconv-1.15.tar.gz
pushd libiconv-1.15
./configure --host=$target_host --prefix=$prefix_path --libdir=$prefix_path/lib64
make
make install
popd
rm libiconv-1.15.tar.gz
rm -r libiconv-1.15
fi
# Cross build libffi
wget --quiet https://github.com/libffi/libffi/releases/download/v3.3-rc0/libffi-3.3-rc0.tar.gz
echo "e6e695d32cd6eb7d65983f32986fccdfc786a593d2ea18af30ce741f58cfa1eb264b1a8d09df5084cb916001aea15187b005c2149a0620a44397a4453b6137d4 libffi-3.3-rc0.tar.gz" | sha512sum -c
tar xzf libffi-3.3-rc0.tar.gz
pushd libffi-3.3-rc0
./configure --host=$target_host --prefix=$prefix_path --libdir=$prefix_path/lib64
make
make install
popd
rm libffi-3.3-rc0.tar.gz
rm -r libffi-3.3-rc0
# Create a pkg-config wrapper that won't pick fedora libraries
mkdir -p $prefix_path/bin
export PKG_CONFIG=$prefix_path/bin/pkg-config
cat > $PKG_CONFIG <<- EOM
#!/bin/sh
SYSROOT=${prefix_path}
export PKG_CONFIG_DIR=
export PKG_CONFIG_LIBDIR=\${SYSROOT}/lib64/pkgconfig
export PKG_CONFIG_SYSROOT_DIR=\${SYSROOT}
exec pkg-config "\$@"
EOM
chmod +x $PKG_CONFIG
# Create a cross file that can be passed to meson
cat > cross_file_android_${arch}_${api}.txt <<- EOM
[host_machine]
system = 'android'
cpu_family = 'arm64'
cpu = 'arm64'
endian = 'little'
[properties]
c_args = ['-I${prefix_path}/include']
c_link_args = ['-L${prefix_path}/lib64',
'-fuse-ld=gold']
[binaries]
c = '${toolchain_path}/bin/${CC}'
cpp = '${toolchain_path}/bin/${CXX}'
ar = '${toolchain_path}/bin/${AR}'
strip = '${toolchain_path}/bin/${STRIP}'
pkgconfig = '${PKG_CONFIG}'
EOM
.gitlab-ci/coverage-docker.sh
Executable
+32
View File
@@ -0,0 +1,32 @@
#!/bin/bash
set -e
# Fixup Windows paths
python3 ./.gitlab-ci/fixup-cov-paths.py _coverage/*.lcov
for path in _coverage/*.lcov; do
# Remove coverage from generated code in the build directory
lcov --config-file .gitlab-ci/lcovrc -r "${path}" '*/_build/*' -o "$(pwd)/${path}"
# Remove any coverage from system files
lcov --config-file .gitlab-ci/lcovrc -e "${path}" "$(pwd)/*" -o "$(pwd)/${path}"
done
genhtml \
--ignore-errors=source \
--config-file .gitlab-ci/lcovrc \
_coverage/*.lcov \
-o _coverage/coverage
cd _coverage
rm -f *.lcov
cat >index.html <<EOL
<html>
<body>
<ul>
<li><a href="coverage/index.html">Coverage</a></li>
</ul>
</body>
</html>
EOL
.gitlab-ci/cross_file_mingw64.txt
+18
View File
@@ -0,0 +1,18 @@
[host_machine]
system = 'windows'
cpu_family = 'x86_64'
cpu = 'x86_64'
endian = 'little'
[properties]
c_args = []
c_link_args = []
[binaries]
c = 'x86_64-w64-mingw32-gcc'
cpp = 'x86_64-w64-mingw32-g++'
ar = 'x86_64-w64-mingw32-ar'
objcopy = 'x86_64-w64-mingw32-objcopy'
strip = 'x86_64-w64-mingw32-strip'
pkgconfig = 'x86_64-w64-mingw32-pkg-config'
windres = 'x86_64-w64-mingw32-windres'
.gitlab-ci/debian-stable.Dockerfile
+73
View File
@@ -0,0 +1,73 @@
FROM debian:buster
RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
bindfs \
clang \
clang-tools-7 \
dbus \
desktop-file-utils \
elfutils \
findutils \
fuse \
gcc \
g++ \
gettext \
git \
libc6-dev \
gtk-doc-tools \
itstool \
lcov \
libattr1-dev \
libelf-dev \
libffi-dev \
libgamin-dev \
libmount-dev \
libpcre2-dev \
libselinux1-dev \
libxml2-utils \
libxslt1-dev \
libz3-dev \
locales \
ninja-build \
python3 \
python3-pip \
python3-setuptools \
python3-wheel \
shared-mime-info \
systemtap-sdt-dev \
unzip \
wget \
xsltproc \
xz-utils \
zlib1g-dev \
&& rm -rf /usr/share/doc/* /usr/share/man/*
# Locale for our build
RUN locale-gen C.UTF-8 && /usr/sbin/update-locale LANG=C.UTF-8
# Locales for our tests
RUN locale-gen de_DE.UTF-8 \
&& locale-gen el_GR.UTF-8 \
&& locale-gen en_US.UTF-8 \
&& locale-gen es_ES.UTF-8 \
&& locale-gen fa_IR.UTF-8 \
&& locale-gen fr_FR.UTF-8 \
&& locale-gen hr_HR.UTF-8 \
&& locale-gen ja_JP.UTF-8 \
&& locale-gen lt_LT.UTF-8 \
&& locale-gen pl_PL.UTF-8 \
&& locale-gen ru_RU.UTF-8 \
&& locale-gen tr_TR.UTF-8
ENV LANG=C.UTF-8 LANGUAGE=C.UTF-8 LC_ALL=C.UTF-8
RUN pip3 install meson==0.49.2
ARG HOST_USER_ID=5555
ENV HOST_USER_ID ${HOST_USER_ID}
RUN useradd -u $HOST_USER_ID -ms /bin/bash user
USER user
WORKDIR /home/user
ENV LANG=C.UTF-8 LANGUAGE=C.UTF-8 LC_ALL=C.UTF-8
.gitlab-ci/fedora.Dockerfile
+65
View File
@@ -0,0 +1,65 @@
FROM fedora:29
RUN dnf -y install \
bindfs \
clang \
clang-analyzer \
dbus-daemon \
desktop-file-utils \
elfutils-libelf-devel \
findutils \
fuse \
gamin-devel \
gcc \
gcc-c++ \
gettext \
git \
glibc-devel \
glibc-headers \
glibc-langpack-de \
glibc-langpack-el \
glibc-langpack-el \
glibc-langpack-en \
glibc-langpack-es \
glibc-langpack-es \
glibc-langpack-fa \
glibc-langpack-fr \
glibc-langpack-hr \
glibc-langpack-ja \
glibc-langpack-lt \
glibc-langpack-pl \
glibc-langpack-ru \
glibc-langpack-tr \
gtk-doc \
itstool \
lcov \
libattr-devel \
libffi-devel \
libmount-devel \
libselinux-devel \
libxslt \
ncurses-compat-libs \
ninja-build \
pcre-devel \
python3 \
python3-pip \
python3-wheel \
shared-mime-info \
systemtap-sdt-devel \
unzip \
valgrind \
wget \
xz \
zlib-devel \
&& dnf clean all
RUN pip3 install meson==0.49.2
ARG HOST_USER_ID=5555
ENV HOST_USER_ID ${HOST_USER_ID}
RUN useradd -u $HOST_USER_ID -ms /bin/bash user
USER user
WORKDIR /home/user
ENV LANG C.UTF-8
.gitlab-ci/fixup-cov-paths.py
+29
View File
@@ -0,0 +1,29 @@
import sys
import os
import io
def main(argv):
# Fix paths in lcov files generated on a Windows host so they match our
# current source layout.
paths = argv[1:]
for path in paths:
print("cov-fixup:", path)
text = io.open(path, "r", encoding="utf-8").read()
text = text.replace("\\\\", "/")
glib_dir = "/glib/"
end = text.index(glib_dir)
start = text[:end].rindex(":") + 1
old_root = text[start:end]
assert os.path.basename(os.getcwd()) == "glib"
new_root = os.path.dirname(os.getcwd())
if old_root != new_root:
print("replacing %r with %r" % (old_root, new_root))
text = text.replace(old_root, new_root)
with io.open(path, "w", encoding="utf-8") as h:
h.write(text)
if __name__ == "__main__":
sys.exit(main(sys.argv))
.gitlab-ci/lcovrc
+13
View File
@@ -0,0 +1,13 @@
# lcov and genhtml configuration
# See http://ltp.sourceforge.net/coverage/lcov/lcovrc.5.php
# Always enable branch coverage
lcov_branch_coverage = 1
# Exclude precondition assertions, as we can never reasonably get full branch
# coverage of them, as they should never normally fail.
# See https://github.com/linux-test-project/lcov/issues/44
lcov_excl_br_line = LCOV_EXCL_BR_LINE|g_return_if_fail|g_return_val_if_fail|g_assert|g_assert_
# Similarly for unreachable assertions.
lcov_excl_line = LCOV_EXCL_LINE|g_return_if_reached|g_return_val_if_reached|g_assert_not_reached
.gitlab-ci/meson-junit-report.py
Executable
+111
View File
@@ -0,0 +1,111 @@
#!/usr/bin/env python3
# Turns a Meson testlog.json file into a JUnit XML report
#
# Copyright 2019 GNOME Foundation
#
# SPDX-License-Identifier: LGPL-2.1-or-later
#
# Original author: Emmanuele Bassi
import argparse
import datetime
import json
import os
import sys
import xml.etree.ElementTree as ET
aparser = argparse.ArgumentParser(description='Turns a Meson test log into a JUnit report')
aparser.add_argument('--project-name', metavar='NAME',
help='The project name',
default='unknown')
aparser.add_argument('--job-id', metavar='ID',
help='The job ID for the report',
default='Unknown')
aparser.add_argument('--branch', metavar='NAME',
help='Branch of the project being tested',
default='master')
aparser.add_argument('--output', metavar='FILE',
help='The output file, stdout by default',
type=argparse.FileType('w', encoding='UTF-8'),
default=sys.stdout)
aparser.add_argument('infile', metavar='FILE',
help='The input testlog.json, stdin by default',
type=argparse.FileType('r', encoding='UTF-8'),
default=sys.stdin)
args = aparser.parse_args()
outfile = args.output
testsuites = ET.Element('testsuites')
testsuites.set('id', '{}/{}'.format(args.job_id, args.branch))
testsuites.set('package', args.project_name)
testsuites.set('timestamp', datetime.datetime.utcnow().isoformat())
suites = {}
for line in args.infile:
data = json.loads(line)
(full_suite, unit_name) = data['name'].split(' / ')
(project_name, suite_name) = full_suite.split(':')
duration = data['duration']
return_code = data['returncode']
log = data['stdout']
log_stderr = data.get('stderr', '')
unit = {
'suite': suite_name,
'name': unit_name,
'duration': duration,
'returncode': return_code,
'stdout': log,
'stderr': log_stderr,
}
units = suites.setdefault(suite_name, [])
units.append(unit)
for name, units in suites.items():
print('Processing suite {} (units: {})'.format(name, len(units)))
def if_failed(unit):
if unit['returncode'] != 0:
return True
return False
def if_succeded(unit):
if unit['returncode'] == 0:
return True
return False
successes = list(filter(if_succeded, units))
failures = list(filter(if_failed, units))
print(' - {}: {} pass, {} fail'.format(name, len(successes), len(failures)))
testsuite = ET.SubElement(testsuites, 'testsuite')
testsuite.set('name', '{}/{}'.format(args.project_name, name))
testsuite.set('tests', str(len(units)))
testsuite.set('errors', str(len(failures)))
testsuite.set('failures', str(len(failures)))
for unit in successes:
testcase = ET.SubElement(testsuite, 'testcase')
testcase.set('classname', '{}/{}'.format(args.project_name, unit['suite']))
testcase.set('name', unit['name'])
testcase.set('time', str(unit['duration']))
for unit in failures:
testcase = ET.SubElement(testsuite, 'testcase')
testcase.set('classname', '{}/{}'.format(args.project_name, unit['suite']))
testcase.set('name', unit['name'])
testcase.set('time', str(unit['duration']))
failure = ET.SubElement(testcase, 'failure')
failure.set('classname', '{}/{}'.format(args.project_name, unit['suite']))
failure.set('name', unit['name'])
failure.set('type', 'error')
failure.text = unit['stdout'] + '\n' + unit['stderr']
output = ET.tostring(testsuites, encoding='unicode')
outfile.write(output)
.gitlab-ci/mingw.Dockerfile
+70
View File
@@ -0,0 +1,70 @@
FROM fedora:29
RUN dnf -y install \
bindfs \
clang \
clang-analyzer \
desktop-file-utils \
elfutils-libelf-devel \
findutils \
fuse \
gamin-devel \
gcc \
gcc-c++ \
gettext \
git \
glibc-devel \
glibc-headers \
glibc-langpack-de \
glibc-langpack-el \
glibc-langpack-el \
glibc-langpack-en \
glibc-langpack-es \
glibc-langpack-es \
glibc-langpack-fa \
glibc-langpack-fr \
glibc-langpack-hr \
glibc-langpack-ja \
glibc-langpack-lt \
glibc-langpack-pl \
glibc-langpack-ru \
glibc-langpack-tr \
gtk-doc \
itstool \
lcov \
libattr-devel \
libffi-devel \
libmount-devel \
libselinux-devel \
libxslt \
mingw64-gcc \
mingw64-gcc-c++ \
mingw64-gettext \
mingw64-libffi \
mingw64-zlib \
ncurses-compat-libs \
ninja-build \
pcre-devel \
python3 \
python3-pip \
python3-wheel \
systemtap-sdt-devel \
unzip \
wget \
xz \
zlib-devel \
&& dnf clean all
WORKDIR /opt
COPY cross_file_mingw64.txt /opt
RUN pip3 install meson==0.49.2
ARG HOST_USER_ID=5555
ENV HOST_USER_ID ${HOST_USER_ID}
RUN useradd -u $HOST_USER_ID -ms /bin/bash user
USER user
WORKDIR /home/user
ENV LANG C.UTF-8
.gitlab-ci/run-docker.sh
Executable
+120
View File
@@ -0,0 +1,120 @@
#!/bin/bash
read_arg() {
# $1 = arg name
# $2 = arg value
# $3 = arg parameter
local rematch='^[^=]*=(.*)$'
if [[ $2 =~ $rematch ]]; then
read "$1" <<< "${BASH_REMATCH[1]}"
else
read "$1" <<< "$3"
# There is no way to shift our callers args, so
# return 1 to indicate they should do it instead.
return 1
fi
}
set -e
build=0
run=0
push=0
list=0
print_help=0
no_login=0
while (($# > 0)); do
case "${1%%=*}" in
build) build=1;;
run) run=1;;
push) push=1;;
list) list=1;;
help) print_help=1;;
--base|-b) read_arg base "$@" || shift;;
--base-version) read_arg base_version "$@" || shift;;
--no-login) no_login=1;;
*) echo -e "\e[1;31mERROR\e[0m: Unknown option '$1'"; exit 1;;
esac
shift
done
if [ $print_help == 1 ]; then
echo "$0 - Build and run Docker images"
echo ""
echo "Usage: $0 <command> [options] [basename]"
echo ""
echo "Available commands"
echo ""
echo " build --base=<BASENAME> - Build Docker image <BASENAME>.Dockerfile"
echo " run --base=<BASENAME> - Run Docker image <BASENAME>"
echo " push --base=<BASENAME> - Push Docker image <BASENAME> to the registry"
echo " list - List available images"
echo " help - This help message"
echo ""
exit 0
fi
cd "$(dirname "$0")"
if [ $list == 1 ]; then
echo "Available Docker images:"
for f in *.Dockerfile; do
filename=$( basename -- "$f" )
basename="${filename%.*}"
echo -e " \e[1;39m$basename\e[0m"
done
exit 0
fi
# All commands after this require --base to be set
if [ -z $base ]; then
echo "Usage: $0 <command>"
exit 1
fi
if [ ! -f "$base.Dockerfile" ]; then
echo -e "\e[1;31mERROR\e[0m: Dockerfile for '$base' not found"
exit 1
fi
if [ -z $base_version ]; then
base_version="latest"
else
base_version="v$base_version"
fi
TAG="registry.gitlab.gnome.org/gnome/glib/${base}:${base_version}"
if [ $build == 1 ]; then
echo -e "\e[1;32mBUILDING\e[0m: ${base} as ${TAG}"
sudo docker build \
--build-arg HOST_USER_ID="$UID" \
--tag "${TAG}" \
--file "${base}.Dockerfile" .
exit $?
fi
if [ $push == 1 ]; then
echo -e "\e[1;32mPUSHING\e[0m: ${base} as ${TAG}"
if [ $no_login == 0 ]; then
sudo docker login registry.gitlab.gnome.org
fi
sudo docker push $TAG
exit $?
fi
if [ $run == 1 ]; then
echo -e "\e[1;32mRUNNING\e[0m: ${base} as ${TAG}"
sudo docker run \
--rm \
--volume "$(pwd)/..:/home/user/app" \
--workdir "/home/user/app" \
--tty \
--interactive "${TAG}" \
bash
exit $?
fi
.gitlab-ci/run-tests.sh
Executable
+29
View File
@@ -0,0 +1,29 @@
#!/bin/bash
set +e
case "$1" in
--log-file)
log_file="$2"
shift
shift
;;
*)
log_file="_build/meson-logs/testlog.json"
esac
meson test \
-C _build \
--timeout-multiplier ${MESON_TEST_TIMEOUT_MULTIPLIER} \
--no-suite flaky \
"$@"
exit_code=$?
python3 .gitlab-ci/meson-junit-report.py \
--project-name=glib \
--job-id "${CI_JOB_NAME}" \
--output "_build/${CI_JOB_NAME}-report.xml" \
"${log_file}"
exit $exit_code
.gitlab-ci/test-msvc.bat
+24
View File
@@ -0,0 +1,24 @@
@echo on
:: vcvarsall.bat sets various env vars like PATH, INCLUDE, LIB, LIBPATH for the
:: specified build architecture
call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
@echo on
:: FIXME: make warnings fatal
pip3 install --upgrade --user meson==0.49.2 || goto :error
meson _build || goto :error
ninja -C _build || goto :error
:: FIXME: dont ignore test errors
meson test -C _build --timeout-multiplier %MESON_TEST_TIMEOUT_MULTIPLIER% --no-suite flaky
:: FIXME: can we get code coverage support?
python "%CD%\.gitlab-ci\meson-junit-report.py" --project-name glib ^
--job-id "%CI_JOB_NAME%" --output "%CD%/_build/%CI_JOB_NAME%-report.xml" ^
"%CD%/_build/meson-logs/testlog.json"
goto :EOF
:error
exit /b 1
.gitlab-ci/test-msys2.sh
Executable
+70
View File
@@ -0,0 +1,70 @@
#!/bin/bash
set -e
export PATH="/c/msys64/$MSYSTEM/bin:$PATH"
if [[ "$MSYSTEM" == "MINGW32" ]]; then
export MSYS2_ARCH="i686"
else
export MSYS2_ARCH="x86_64"
fi
pacman --noconfirm -Suy
pacman --noconfirm -S --needed \
base-devel \
mingw-w64-$MSYS2_ARCH-ccache \
mingw-w64-$MSYS2_ARCH-gettext \
mingw-w64-$MSYS2_ARCH-libffi \
mingw-w64-$MSYS2_ARCH-meson \
mingw-w64-$MSYS2_ARCH-pcre \
mingw-w64-$MSYS2_ARCH-python3 \
mingw-w64-$MSYS2_ARCH-python3-pip \
mingw-w64-$MSYS2_ARCH-toolchain \
mingw-w64-$MSYS2_ARCH-zlib \
mingw-w64-$MSYS2_ARCH-libelf
curl -O -J -L "https://github.com/linux-test-project/lcov/releases/download/v1.14/lcov-1.14.tar.gz"
echo "14995699187440e0ae4da57fe3a64adc0a3c5cf14feab971f8db38fb7d8f071a lcov-1.14.tar.gz" | sha256sum -c
tar -xzf lcov-1.14.tar.gz
LCOV="$(pwd)/lcov-1.14/bin/lcov"
mkdir -p _coverage
mkdir -p _ccache
export CCACHE_BASEDIR="$(pwd)"
export CCACHE_DIR="${CCACHE_BASEDIR}/_ccache"
pip3 install --upgrade --user meson==0.49.2
export PATH="$HOME/.local/bin:$PATH"
export CFLAGS="-coverage -ftest-coverage -fprofile-arcs"
DIR="$(pwd)"
meson --werror --buildtype debug _build
cd _build
ninja
# FIXME: lcov doesn't support gcc9 yet:
# https://github.com/linux-test-project/lcov/issues/58
#"${LCOV}" \
# --quiet \
# --config-file "${DIR}"/.gitlab-ci/lcovrc \
# --directory "${DIR}/_build" \
# --capture \
# --initial \
# --output-file "${DIR}/_coverage/${CI_JOB_NAME}-baseline.lcov"
# FIXME: fix the test suite
meson test --timeout-multiplier ${MESON_TEST_TIMEOUT_MULTIPLIER} --no-suite flaky || true
python3 "${DIR}"/.gitlab-ci/meson-junit-report.py \
--project-name glib \
--job-id "${CI_JOB_NAME}" \
--output "${DIR}/_build/${CI_JOB_NAME}-report.xml" \
"${DIR}/_build/meson-logs/testlog.json"
# FIXME: see above
#"${LCOV}" \
# --quiet \
# --config-file "${DIR}"/.gitlab-ci/lcovrc \
# --directory "${DIR}/_build" \
# --capture \
# --output-file "${DIR}/_coverage/${CI_JOB_NAME}.lcov"
AUTHORS
+40
View File
@@ -0,0 +1,40 @@
Below are just a few of the people who have contributed
to GLib. Please don't mail these people about problems you
have with GLib; see the README.md file for information about
filing bugs and submitting changes.
GLib-2.0 Team
-------------
Hans Breuer <hans@breuer.org>
Matthias Clasen <mclasen@redhat.com>
Tor Lillqvist <tml@iki.fi>
Tim Janik <timj@gtk.org>
Havoc Pennington <hp@redhat.com>
Ron Steinke <rsteinke@w-link.net>
Owen Taylor <otaylor@redhat.com>
Sebastian Wilhelmi <seppi@seppi.de>
GLib-1.2 Team
-------------
Shawn T. Amundson <amundson@gimp.org>
Jeff Garzik <jgarzik@pobox.com>
Raja R Harinath <harinath@cs.umn.edu>
Tim Janik <timj@gtk.org>
Elliot Lee <sopwith@redhat.com>
Tor Lillqvist <tml@iki.fi>
Paolo Molaro <lupus@debian.org>
Havoc Pennington <hp@pobox.com>
Manish Singh <yosh@gimp.org>
Owen Taylor <otaylor@gtk.org>
Sebastian Wilhelmi <wilhelmi@ira.uka.de>
The random number generator "Mersenne Twister", which is used by GLib,
was developed and originally coded by:
Makoto Matsumoto <matumoto@math.keio.ac.jp>
Takuji Nishimura <nisimura@math.keio.ac.jp>
Original Authors
----------------
Peter Mattis <petm@xcf.berkeley.edu>
Spencer Kimball <spencer@xcf.berkeley.edu>
Josh MacDonald <jmacd@xcf.berkeley.edu>
BUILD.gn
Executable
+257
View File
@@ -0,0 +1,257 @@
# Copyright (c) Huawei Technologies Co., Ltd. 2021. All rights reserved.
import("//build/ohos.gni")
group("glib_packages") {
deps = [
":glib",
":gmodule",
":gobject",
]
}
config("glib_config") {
visibility = [ ":*" ]
include_dirs = [
".",
"glib/libcharset",
"glib/pcre",
"glib",
"glib/deprecated",
]
cflags = [
"-DG_LOG_DOMAIN=\"GLib\"",
"-DGLIB_CHARSETALIAS_DIR=\"system/lib64\"",
"-DHAVE_MEMMOVE",
"-DSUPPORT_UCP",
"-DSUPPORT_UTF",
"-DSUPPORT_UTF8",
"-DNEWLINE=-1",
"-DMATCH_LIMIT=10000000",
"-DMATCH_LIMIT_RECURSION=8192",
"-DMAX_NAME_SIZE=32",
"-DMAX_NAME_COUNT=10000",
"-DMAX_DUPLENGTH=30000",
"-DLINK_SIZE=2",
"-DPOSIX_MALLOC_THRESHOLD=10",
"-DPCRE_STATIC",
"-UBSR_ANYCRLF",
"-UEBCDIC",
"-DGLIB_COMPILATION",
"-Wno-sign-compare",
"-Wno-unused-value",
"-Wno-int-conversion",
]
}
ohos_source_set("glib_source") {
sources = [
"glib/libcharset/localcharset.c",
"glib/pcre/pcre_byte_order.c",
"glib/pcre/pcre_chartables.c",
"glib/pcre/pcre_compile.c",
"glib/pcre/pcre_config.c",
"glib/pcre/pcre_dfa_exec.c",
"glib/pcre/pcre_exec.c",
"glib/pcre/pcre_fullinfo.c",
"glib/pcre/pcre_get.c",
"glib/pcre/pcre_globals.c",
"glib/pcre/pcre_jit_compile.c",
"glib/pcre/pcre_newline.c",
"glib/pcre/pcre_ord2utf8.c",
"glib/pcre/pcre_string_utils.c",
"glib/pcre/pcre_study.c",
"glib/pcre/pcre_tables.c",
"glib/pcre/pcre_valid_utf8.c",
"glib/pcre/pcre_version.c",
"glib/pcre/pcre_xclass.c",
"glib/deprecated/gallocator.c",
"glib/deprecated/gcache.c",
"glib/deprecated/gcompletion.c",
"glib/deprecated/grel.c",
"glib/deprecated/gthread-deprecated.c",
"glib/garcbox.c",
"glib/garray.c",
"glib/gasyncqueue.c",
"glib/gatomic.c",
"glib/gbacktrace.c",
"glib/gbase64.c",
"glib/gbitlock.c",
"glib/gbookmarkfile.c",
"glib/gbytes.c",
"glib/gcharset.c",
"glib/gchecksum.c",
"glib/gconvert.c",
"glib/gdataset.c",
"glib/gdate.c",
"glib/gdatetime.c",
"glib/gdir.c",
"glib/genviron.c",
"glib/gerror.c",
"glib/gfileutils.c",
"glib/ggettext.c",
"glib/ghash.c",
"glib/ghmac.c",
"glib/ghook.c",
"glib/ghostutils.c",
"glib/giochannel.c",
"glib/gkeyfile.c",
"glib/glib-init.c",
"glib/glib-private.c",
"glib/glist.c",
"glib/gmain.c",
"glib/gmappedfile.c",
"glib/gmarkup.c",
"glib/gmem.c",
"glib/gmessages.c",
"glib/gnode.c",
"glib/goption.c",
"glib/gpattern.c",
"glib/gpoll.c",
"glib/gprimes.c",
"glib/gqsort.c",
"glib/gquark.c",
"glib/gqueue.c",
"glib/grand.c",
"glib/grcbox.c",
"glib/grefcount.c",
"glib/grefstring.c",
"glib/gregex.c",
"glib/gscanner.c",
"glib/gsequence.c",
"glib/gshell.c",
"glib/gslice.c",
"glib/gslist.c",
"glib/gstdio.c",
"glib/gstrfuncs.c",
"glib/gstring.c",
"glib/gstringchunk.c",
"glib/gtestutils.c",
"glib/gthread.c",
"glib/gthreadpool.c",
"glib/gtimer.c",
"glib/gtimezone.c",
"glib/gtranslit.c",
"glib/gtrashstack.c",
"glib/gtree.c",
"glib/guniprop.c",
"glib/gutf8.c",
"glib/gunibreak.c",
"glib/gunicollate.c",
"glib/gunidecomp.c",
"glib/gurifuncs.c",
"glib/gutils.c",
"glib/gutilsprivate.h",
"glib/guuid.c",
"glib/gvariant.c",
"glib/gvariant-core.c",
"glib/gvariant-parser.c",
"glib/gvariant-serialiser.c",
"glib/gvarianttypeinfo.c",
"glib/gvarianttype.c",
"glib/gversion.c",
"glib/gwakeup.c",
"glib/gprintf.c",
"glib/glib-unix.c",
"glib/gspawn.c",
"glib/giounix.c",
"glib/gthread-posix.c",
]
configs = [
":glib_config",
]
}
ohos_shared_library("glib") {
deps = [
":glib_source",
]
part_name = "multimedia_histreamer"
subsystem_name = "multimedia"
}
config("gmodule_config") {
visibility = [ ":*" ]
include_dirs = [
".",
"gmodule",
"glib",
]
cflags = [
"-DG_LOG_DOMAIN=\"GModule\""
]
}
ohos_source_set("gmodule_source") {
sources = [
"gmodule/gmodule.c",
]
configs = [
":gmodule_config",
]
}
ohos_shared_library("gmodule") {
deps = [
":gmodule_source",
":glib",
]
part_name = "multimedia_histreamer"
subsystem_name = "multimedia"
}
config("gobject_config") {
visibility = [ ":*" ]
include_dirs = [
".",
"gobject",
"glib",
"//third_party/libffi/include",
]
cflags = [
"-DG_LOG_DOMAIN=\"GObject\"",
"-DGOBJECT_COMPILATION",
"-Wno-sign-compare",
"-Wno-unused-function",
"-Wno-int-conversion",
]
}
ohos_source_set("gobject_source") {
sources = [
"gobject/gatomicarray.c",
"gobject/gbinding.c",
"gobject/gboxed.c",
"gobject/gclosure.c",
"gobject/genums.c",
"gobject/gmarshal.c",
"gobject/gobject.c",
"gobject/gparam.c",
"gobject/gparamspecs.c",
"gobject/gsignal.c",
"gobject/gsourceclosure.c",
"gobject/gtype.c",
"gobject/gtypemodule.c",
"gobject/gtypeplugin.c",
"gobject/gvalue.c",
"gobject/gvaluearray.c",
"gobject/gvaluetransform.c",
"gobject/gvaluetypes.c",
]
configs = [
":gobject_config",
]
}
ohos_shared_library("gobject") {
deps = [
":gobject_source",
":glib",
"//third_party/libffi:ffi",
]
part_name = "multimedia_histreamer"
subsystem_name = "multimedia"
}
CONTRIBUTING.md
+274
View File
@@ -0,0 +1,274 @@
# Contribution guidelines
Thank you for considering contributing to the GLib project!
These guidelines are meant for new contributors, regardless of their level
of proficiency; following them allows the core developers of the GLib project to
more effectively evaluate your contribution, and provide prompt feedback to
you. Additionally, by following these guidelines you clearly communicate
that you respect the time and effort that the people developing GLib put into
managing the project.
GLib is a complex free software utility library, and it would not exist without
contributions from the free and open source software community. There are
many things that we value:
- bug reporting and fixing
- documentation and examples
- tests
- testing and support for other platforms
- new features
Please, do not use the issue tracker for support questions. If you have
questions on how to use GLib effectively, you can use:
- the `#gtk` IRC channel on irc.gnome.org
- the [`glib` tag on GNOME's Discourse](https://discourse.gnome.org/tags/glib)
You can also look at the [`glib` tag on Stack
Overflow](https://stackoverflow.com/questions/tagged/glib).
The issue tracker is meant to be used for actionable issues only.
## How to report bugs
### Security issues
You should not open a new issue for security related questions.
When in doubt, send an email to the [security](mailto:security@gnome.org)
mailing list.
### Bug reports
If you’re reporting a bug make sure to list:
0. which version of GLib are you using?
0. which operating system are you using?
0. the necessary steps to reproduce the issue
0. the expected outcome
0. a description of the behavior
0. a small, self-contained example exhibiting the behavior
If the issue includes a crash, you should also include:
0. the eventual warnings printed on the terminal
0. a backtrace, obtained with tools such as GDB or LLDB
If the issue includes a memory leak, you should also include:
0. a log of definite leaks from a tool such as [valgrind’s
memcheck](http://valgrind.org/docs/manual/mc-manual.html)
For small issues, such as:
- spelling/grammar fixes in the documentation,
- typo correction,
- comment clean ups,
- changes to metadata files (CI, `.gitignore`),
- build system changes, or
- source tree clean ups and reorganizations;
or for self-contained bug fixes where you have implemented and tested a solution
already, you should directly open a merge request instead of filing a new issue.
### Features and enhancements
Feature discussion can be open ended and require high bandwidth channels; if
you are proposing a new feature on the issue tracker, make sure to make
an actionable proposal, and list:
0. what you’re trying to achieve and the problem it solves
0. three (or more) existing pieces of software which would benefit from the
new feature
0. how the feature is implementable on platforms other than Linux
New APIs, in particular, should follow the ‘rule of three’, where there should
be three (or more) pieces of software which are ready to use the new APIs. This
allows us to check that the new APIs are usable in real-life code, and fit well
with related APIs. This reduces the chances of awkward or unusable APIs becoming
stable in GLib and having to be supported forever.
A common way to introduce new APIs or data types to GLib is to prototype them in
another code base for a while, to gain real-life experience with them before
they are imported into GLib and marked as stable.
Each feature should also come fully documented, and with tests which approach
full branch coverage of the new code. GLib’s CI system generates code coverage
reports which are viewable for each merge request.
If proposing a large feature or change, it’s better to discuss it (on the
`#gtk` IRC channel or on [Discourse](https://discourse.gnome.org) before
putting time into writing an actionable issue — and certainly before putting
time into writing a merge request.
## Your first contribution
### Prerequisites
If you want to contribute to the GLib project, you will need to have the
development tools appropriate for your operating system, including:
- Python 3.x
- Meson
- Ninja
- Gettext (19.7 or newer)
- a [C99 compatible compiler](https://wiki.gnome.org/Projects/GLib/CompilerRequirements)
Up-to-date instructions about developing GNOME applications and libraries
can be found on [the GNOME Developer Center](https://developer.gnome.org).
The [GLib project uses GitLab](https://gitlab.gnome.org/GNOME/glib/) for code
hosting and for tracking issues. More information about using GitLab can be
found [on the GNOME wiki](https://wiki.gnome.org/GitLab).
### Getting started
You should start by forking the GLib repository from the GitLab web UI, and
cloning from your fork:
```sh
$ git clone https://gitlab.gnome.org/yourusername/glib.git
$ cd glib
```
**Note**: if you plan to push changes to back to the main repository and
have a GNOME account, you can skip the fork, and use the following instead:
```sh
$ git clone git@gitlab.gnome.org:GNOME/glib.git
$ cd glib
```
To compile the Git version of GLib on your system, you will need to
configure your build using Meson:
```sh
$ meson _builddir .
$ cd _builddir
$ ninja
```
Typically, you should work on your own branch:
```sh
$ git checkout -b your-branch
```
Once you’ve finished working on the bug fix or feature, push the branch
to the Git repository and open a new merge request, to let the GLib
core developers review your contribution.
### Code reviews
Each contribution is reviewed by the core developers of the GLib project.
The [CODEOWNERS](./docs/CODEOWNERS) document contains the list of core
contributors to GLib and the areas for which they are responsible; you
should ensure to receive their review and signoff on your changes.
It is our intention that every commit to GLib is reviewed by at least one other
person, including commits from core developers. We all make mistakes and can
always learn from each other, and code review allows that. It also reduces
[bus factor](https://en.wikipedia.org/wiki/Bus_factor) by spreading knowledge
of each commit between at least two people.
With each code review, we intend to:
0. Identify if this is a desirable change or new feature. Ideally for larger
features this will have been discussed (in an issue, on IRC, or on Discourse)
already, so that effort isn’t wasted on putting together merge requests
which will be rejected.
0. Check the design of any new API.
0. Provide realistic estimates of how long a review might take, if it can’t
happen immediately.
0. Ensure that all significant contributions of new code, or bug fixes, are
adequately tested, either through requiring tests to be submitted at the
same time, or as a follow-up.
0. Ensure that all new APIs are documented and have [introspection
annotations](https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations).
0. Check that the contribution is split into logically separate commits, each
with a good commit message.
0. Encourage further high quality contributions.
0. Ensure code style and quality is upheld.
If a code review is stalled (due to not receiving comments for two or more
weeks; or due to a technical disagreement), please ping another GLib core
developer on the merge request, or on IRC, to ask for a second opinion.
### Commit messages
The expected format for git commit messages is as follows:
```plain
Short explanation of the commit
Longer explanation explaining exactly what’s changed, whether any
external or private interfaces changed, what bugs were fixed (with bug
tracker reference if applicable) and so forth. Be concise but not too
brief.
Closes #1234
```
- Always add a brief description of the commit to the _first_ line of
the commit and terminate by two newlines (it will work without the
second newline, but that is not nice for the interfaces).
- First line (the brief description) must only be one sentence and
should start with a capital letter unless it starts with a lowercase
symbol or identifier. Don’t use a trailing period either. Don’t exceed
72 characters.
- The main description (the body) is normal prose and should use normal
punctuation and capital letters where appropriate. Consider the commit
message as an email sent to the developers (or yourself, six months
down the line) detailing **why** you changed something. There’s no need
to specify the **how**: the changes can be inlined.
- When committing code on behalf of others use the `--author` option, e.g.
`git commit -a --author "Joe Coder <joe@coder.org>"` and `--signoff`.
- If your commit is addressing an issue, use the
[GitLab syntax](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html)
to automatically close the issue when merging the commit with the upstream
repository:
```plain
Closes #1234
Fixes #1234
Closes: https://gitlab.gnome.org/GNOME/glib/issues/1234
```
- If you have a merge request with multiple commits and none of them
completely fixes an issue, you should add a reference to the issue in
the commit message, e.g. `Bug: #1234`, and use the automatic issue
closing syntax in the description of the merge request.
### Merge access to the GLib repository
GLib is part of the GNOME infrastructure. At the current time, any
person with write access to the GNOME repository can merge merge requests to
GLib. This is a good thing, in that it allows maintainership to be delegated
and shared as needed. However, GLib is a fairly large and complicated package
that many other things depend on, and which has platform specific behavior — so
to avoid unnecessary breakage, and to take advantage of the knowledge about GLib
that has been built up over the years, we’d like to ask people contributing to
GLib to follow a few rules:
0. Never push to the `master` branch, or any stable branches, directly; you
should always go through a merge request, to ensure that the code is
tested on the CI infrastructure at the very least. A merge request is
also the proper place to get a comprehensive code review from the core
developers of GLib.
0. Always get a code review, even for seemingly trivial changes.
0. Pay attention to the CI results. Merge requests cannot be merged until the
CI passes. If they consistently fail, either something is wrong with the
change, or the CI tests need fixing — in either case, please bring this to
the attention of a core developer rather than overriding the CI.
If you have been contributing to GLib for a while and you don’t have commit
access to the repository, you may ask to obtain it following the [GNOME account
process](https://wiki.gnome.org/AccountsTeam/NewAccounts).
COPYING
+502
View File
@@ -0,0 +1,502 @@
GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts
as the successor of the GNU Library Public License, version 2, hence
the version number 2.1.]
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it. You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use,
not price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.
To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
To protect each distributor, we want to make it very clear that
there is no warranty for the free library. Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
Finally, software patents pose a constant threat to the existence of
any free program. We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder. Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.
Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License. This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License. We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library. The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom. The Lesser General
Public License permits more lax criteria for linking other code with
the library.
We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License. It also provides other free software developers Less
of an advantage over competing non-free programs. These disadvantages
are the reason we use the ordinary General Public License for many
libraries. However, the Lesser license provides advantages in certain
special circumstances.
For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard. To achieve this, non-free programs must be
allowed to use the library. A more frequent case is that a free
library does the same job as widely used non-free libraries. In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.
In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software. For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
"work based on the library" and a "work that uses the library". The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
GNU LESSER GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".
A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work
which has been distributed under these terms. A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library". Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library". The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
a) Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable "work that
uses the Library", as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
b) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (1) uses at run time a
copy of the library already present on the user's computer system,
rather than copying library functions into the executable, and (2)
will operate properly with a modified version of the library, if
the user installs one, as long as the modified version is
interface-compatible with the version that the work was made with.
c) Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
d) If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
e) Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
a) Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
b) Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
To apply these terms, attach the following notices to the library. It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
<one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James Random Hacker.
<signature of Ty Coon>, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!
HACKING
+17
View File
@@ -0,0 +1,17 @@
If you want to hack on the GLib project, you'll need to have the
following packages installed:
- Meson 0.48.0
- GNU gettext 0.10.40
- pkg-config 0.16
- gtk-doc
- libffi 3.0.0
To compile a Git version of glib on your system, you will need to take
several steps to setup the tree for compilation. You can do all these
steps at once by running:
checkout/glib# meson _build
For information about submitting patches see the CONTRIBUTING.md file. For
information about major design decisions, see the README.rationale file.
INSTALL.in
+125
View File
@@ -0,0 +1,125 @@
Simple install procedure
========================
% tar xf glib-@GLIB_VERSION@.tar.gz # unpack the sources
% cd glib-@GLIB_VERSION@ # change to the toplevel directory
% meson _build # configure the build
% ninja -C _build # build GLib
[ Become root if necessary ]
% ninja -C _build install # install GLib
Requirements
============
GLib requires a C90-compliant (but not necessarily C99-compliant) C
compiler and libc. On UNIX-like systems, it also assumes compliance
with at least the original 1990 version of POSIX.
GLib-2.0 requires pkg-config, which is tool for tracking the
compilation flags needed for libraries. (For each library, a small .pc
text file is installed in a standard location that contains the
compilation flags needed for that library along with version number
information.) Information about pkg-config can be found at:
http://www.freedesktop.org/software/pkgconfig/
Meson (http://mesonbuild.com/) is also required.
In order to implement conversions between character sets,
GLib requires an implementation of the standard iconv() routine.
Most modern systems will have a suitable implementation, however
many older systems lack an iconv() implementation. On such systems,
you must install the libiconv library. This can be found at:
http://www.gnu.org/software/libiconv/
If your system has an iconv implementation but you want to use
libiconv instead, you can pass the --with-libiconv option to
configure. This forces libiconv to be used.
Note that if you have libiconv installed in your default include
search path (for instance, in /usr/local/), but don't enable
it, you will get an error while compiling GLib because the
iconv.h that libiconv installs hides the system iconv.
If you are using the native iconv implementation on Solaris
instead of libiconv, you'll need to make sure that you have
the converters between locale encodings and UTF-8 installed.
At a minimum you'll need the SUNWuiu8 package. You probably
should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
SUNWkiu8 packages.
The native iconv on Compaq Tru64 doesn't contain support for
UTF-8, so you'll need to use GNU libiconv instead. (When
using GNU libiconv for GLib, you'll need to use GNU libiconv
for GNU gettext as well.) This probably applies to related
operating systems as well.
Finally, for message catalog handling, GLib requires an implementation
of gettext(). If your system doesn't provide this functionality,
you should use the libintl library from the GNU gettext package,
available from:
http://www.gnu.org/software/gettext/
Support for extended attributes and SELinux in GIO requires
libattr and libselinux.
Some of the mimetype-related functionality in GIO requires the
update-mime-database and update-desktop-database utilities, which
are part of shared-mime-info and desktop-file-utils, respectively.
GObject uses libffi to implement generic marshalling functionality.
The Nitty-Gritty
================
Complete information about installing GLib can be found
in the file:
docs/reference/glib/html/glib-building.html
Or online at:
https://developer.gnome.org/glib/stable/glib-building.html
Installation directories
========================
The location of the installed files is determined by the --prefix
and --exec-prefix options given to configure. There are also more
detailed flags to control individual directories. However, the
use of these flags is not tested.
One particular detail to note, is that the architecture-dependent
include file glibconfig.h is installed in:
$exec_prefix/lib/glib/include/
if you have a version in $prefix/include, this is out of date
and should be deleted.
.pc files for the various libraries are installed in
$exec_prefix/lib/pkgconfig to provide information when compiling
other packages that depend on GLib. If you set PKG_CONFIG_PATH
so that it points to this directory, then you can get the
correct include flags and library flags for compiling a GLib
application with:
pkg-config --cflags glib-2.0
pkg-config --libs glib-2.0
Cross-compiling GLib
====================
Information about cross-compilation of GLib can be found
in the file:
docs/reference/glib/html/glib-cross-compiling.html
Or online at:
https://developer.gnome.org/glib/stable/glib-cross-compiling.html
NEWS
+11917
View File
File diff suppressed because it is too large Load Diff
NEWS.pre-1-3
+211
View File
@@ -0,0 +1,211 @@
Overview of Changes in GLib 1.2.1:
* g_realloc() fix for SunOS (please report further problems).
* Continued the never ending fix vendetta regarding getpwuid(),
this time AIX has been the culprit.
* Upgrade to libtool 1.2f
* Miscellaneous other buglets fixed.
What's new in GLib 1.2.0 (since GLib 1.0.x):
* GLib is distributed seperatedly from Gtk+
* Win32 Portability
* Threading support
* GModule mechanism (implemented in an extra library) which wraps dynamic
object code loading facilities in a portable manner
* GIOChannel structure to encapsulate the IPC mechanism
* GQuarks and datasets
* GRelations for n-way mapping of certain data
* An n-way tree implementation
* GDate functionality for calendar date manipulations
* GAllocator type and associated functions
* Added generic callback maintenance functions (ghook)
* Generic functions for TAB completions
* Endian defines (G_*_ENDIAN)
* g_log() mechanism for logging of messages at different log levels
* Generic main-loop mechanism
* New glib-config helper script
* Many more API extensions
Overview of Changes in GLib 1.1.16:
* Allocate smaller pools of memory for glists, gslists, gnodes
* Bug Fixes
Overview of Changes in GLib 1.1.15:
* HPUX 11 thread system detection should now work
* Release the main loop lock around calls to prepare() and
check() so it is not held over user code
* A few Win32 fixups
Overview of Changes in GLib 1.1.14:
* Check for dlsym() in system libraries and -dl
* FreeBSD portability fixes
* Random bug fixes and autoconf/automake changes
Overview of Changes in GLib 1.1.13:
* Removed alloca() based function and macro variants again.
* Improved thread related configure tests.
* GSource destruction fixups.
* Fixed up idle function removal based on user_data pointer.
* Advanced Win32 portability.
* Enforced GSource's check(), prepare() and dispatch() constrains,
loop recursions may only happen from dispatch(), and check() as well
as prepare() are called while the main_loop lock is being held.
* GLib development now requires GNU autoconf 2.13, GNU automake 1.4
and GNU libtool 1.2d.
* Lots of random portability and bug fixes.
Overview of Changes in GLib 1.1.12:
* Added alloca functions/macros: g_strdup_a, g_strconcat3_a, g_alloca,
g_new_a, g_new0_a
* New tests structure. Type 'make check' on your system to run them.
* Avoid unnecessary extra hook referencing in g_hook_list_marshal
Overview of Changes in GLib 1.1.11:
* provide defaults for POLL sysdefs
* g_main_is_running: new function to check whether a main loop has been quitted
* a few other enhancement/fixes
Overview of Changes in GLib 1.1.9:
* Check for pthread_attr_init in all cases, Digital Unix 4 requires this
* For G_LOCK_DECLARE_*, if !G_THREADS_ENABLED, eat trailing semicolon better
* Changed g_main_poll_(add|remove) to g_main_(add|remove)_poll
Overview of Changes in GLib 1.1.8:
* Added threading support
- The ability to specify a set of functions to be used for
locking at runtime.
- Default implementations of locking functions for pthreads,
Solaris threads, and (experimentally) NSPR.
- All static variables should now properly locked.
- Enhancements to the generic main-loop mechanism to be thread-safe.
(It is used for the main-loop in GTK+ as of GTK+-1.1.8)
* Portability fixes.
Overview of Changes in GLib 1.1.7:
* Removed multiple define from glibconfig.h
Overview of Changes in GLib 1.1.6:
* New GDate functionality for calendar date manipulations (g_date_*)
* New GAllocator type and associated functions
* New functions g_slist_copy and g_list_copy to duplicate a list with all
its data pointers.
* New function g_array_insert_vals and new macro g_array_insert_val to
insert elements at an arbitrary index
* GAllocators used for glist, gslist, gnode node allocations
* Incremental freezing in ghash
* New function g_hook_list_marshal_check to eventually destroy hooks after
they got marshalled
* Revised GIOChannel to provide generic virtual-function based interface
* Added generic main-loop abstraction
* Removed GListAllocator type and its g_*_allocator_*() function variants
* Bug fixes
Overview of Changes in GLib 1.1.5:
* Win32 portability
* GIOChannel structure to encapsulate the IPC mechanism
* Reimplemented endian stuff, using inline asm for x86
* New functions:
- g_strescape: escapes backslashes
- g_path_is_absolute and g_path_skip_root
- g_getenv: expands environment variables that contain references
to other environment variables
- g_scanner_sync_file_offset: rewind the filedescriptor to the current
buffer position and blow the file read ahead buffer
- g_array_remove_index: remove an entry, preserving the order
- g_array_remove_index_fast: remove an entry, order might be distorted
- g_ptr_array_remove: remove an entry, preserving the order
- g_ptr_array_remove_fast: remove an entry, order might be distorted
- g_byte_array_remove_index: wrapper for g_array_remove_index
- g_byte_array_remove_index_fast: wrapper for g_array_remove_index_fast
- g_strncasecmp: modeled closely after g_strcasecmp
- g_list_sort, g_slist_sort: to merge sort GLists and GSLists
* New macros:
- G_DIR_SEPARATOR, G_DIR_SEPARATOR_S: platform-dependant file name
syntax elements
- G_SEARCHPATH_SEPARATOR, G_SEARCHPATH_SEPARATOR_S: platform-dependant
search path syntax conventions
- G_STRUCT_OFFSET, G_STRUCT_MEMBER_P, G_STRUCT_MEMBER: for handling
structure fields through their offsets
* Removed G_ENUM, G_FLAGS, G_NV, and G_SV macros
* Bug fixes
Overview of Changes in GLib 1.1.4:
* Added generic callback maintenance functions (ghook)
* New endian defines (G_*_ENDIAN)
* New string join/split/free routines
* Fixes
Overview of Changes in GLib 1.1.3:
* New GModule mechanism (implemented in an extra library) which wraps dynamic
object code loading facilities in a portable manner.
* glib-config features extra "glib" (old behaviour remains) and "gmodule"
(add libgmodule.so to the --libs output) arguments now. this can also
be specified as fourth argument to the AM_PATH_GLIB() macro.
* Overhaul of the `inline' autoconfiguration stuff, so inlining should be
sufficiently supported on all systems that allow inlining now.
* New g_log() mechanism for logging of messages at different log levels,
associated with certain log domains (define -DG_LOG_DOMAIN for your library).
* New inline functions for bit masks tests.
* GNode macros (and functions) now return the newly allocated node.
* New macro G_VA_COPY() to work around va_list copying oddities on some
platforms. the non-static g_vsprintf() function vanished in favour of
a publically exported g_strdup_vprintf().
People that used the former g_vsprintf() would definitely want to read the
associated ChangeLog entries (grep for printf).
* New utility functions:
g_strndup(), g_on_error_query(), g_on_error_stack_trace(), g_strdup_printf(),
g_strdup_vprintf(), g_printf_string_upper_bound(), g_spaced_primes_closest(),
g_strnfill(), g_memdup().
* Overhaul of the array implementations, this contains some source incompatible
changes. Again, the ChangeLog is much more informative (grep for garray.c).
* The internals of the g_dataset mechanism are now exported through the
new g_datalist_* API (this is also the underlying implementation for the
keyed data of GtkObjects).
* New function g_atexit(), use of the ATEXIT() macro is discouraged.
* Better configure checks for ansi compliance.
* Libtool update to version 1.2b.
* Lotsa bug fixes and cleanups as always ;)
Overview of Changes in GLib 1.1.2:
* Fixed packaging mistake which occured in 1.1.1
* fix 64-bitness in g_prints in glibtest
What is new in GLib 1.1.1:
* An n-way tree implementation is provided now, based on the GNode structure.
* Bugfix for pointer arrays.
What is new in GLib 1.1.0:
* GLib is distributed seperatedly from Gtk+ now and uses a sophisticated
shared library versioning scheme to deal with interface and binary
incompatibilities.
* There is a glib-config helper script installed now.
* Fixups all over the place.
* gboolean is now a gint, not a gchar anymore.
* API extensions for GList and GSList.
* New g_str*() functions for simple string handling.
* GScanner extensions for scope, warning and error handling.
* Minor performance improvements for GMemChunks.
* Implementations of GQuarks and datasets (similar to GtkObjects data
mechansim, but works for generic memory locations).
* More convenience macros for GNU C function arguments.
* Const correction all over the place, including a new pointer type
gconstpointer.
* Generic functions for TAB completions.
* GRelations for n-way mapping of certain data.
OAT.xml
Executable
+72
View File
@@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (c) 2021 Huawei Device Co., Ltd.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Notes:
This is project config file for OpenHarmony OSS Audit Tool, if you have any questions or concerns, please email chenyaxun@huawei.com.
-->
<!-- OAT(OSS Audit Tool) configuration guide:
basedir: Root dir, the basedir + project path is the real source file location.
licensefile:
1.If the project don't have "LICENSE" in root dir, please define all the license files in this project in , OAT will check license files according to this rule.
tasklist(only for batch mode):
1. task: Define oat check thread, each task will start a new thread.
2. task name: Only an name, no practical effect.
3. task policy: Default policy for projects under this task, this field is required and the specified policy must defined in policylist.
4. task filter: Default filefilter for projects under this task, this field is required and the specified filefilter must defined in filefilterlist.
5. task project: Projects to be checked, the path field define the source root dir of the project.
policyList:
1. policy: All policyitems will be merged to default OAT.xml rules, the name of policy doesn't affect OAT check process.
2. policyitem: The fields type, name, path, desc is required, and the fields rule, group, filefilter is optional,the default value is:
<policyitem type="" name="" path="" desc="" rule="may" group="defaultGroup" filefilter="defaultPolicyFilter"/>
3. policyitem type:
"compatibility" is used to check license compatibility in the specified path;
"license" is used to check source license header in the specified path;
"copyright" is used to check source copyright header in the specified path;
"import" is used to check source dependency in the specified path, such as import ... ,include ...
"filetype" is used to check file type in the specified path, supported file types: archive, binary
"filename" is used to check whether the specified file exists in the specified path(support projectroot in default OAT.xml), supported file names: LICENSE, README, README.OpenSource
4. policyitem name: This field is used for define the license, copyright, "*" means match all, the "!" prefix means could not match this value. For example, "!GPL" means can not use GPL license.
5. policyitem path: This field is used for define the source file scope to apply this policyitem, the "!" prefix means exclude the files. For example, "!.*/lib/.*" means files in lib dir will be exclude while process this policyitem.
6. policyitem rule and group: These two fields are used together to merge policy results. "may" policyitems in the same group means any one in this group passed, the result will be passed.
7. policyitem filefilter: Used to bind filefilter which define filter rules.
8. filefilter: Filter rules, the type filename is used to filter file name, the type filepath is used to filter file path.
Note:If the text contains special characters, please escape them according to the following rules:
" == &gt;
& == &gt;
' == &gt;
< == &gt;
> == &gt;
-->
<configuration>
<oatconfig>
<licensefile>COPYING</licensefile>
<policylist>
<policy name="projectPolicy" desc="">
</policy>
</policylist>
<filefilterlist>
<filefilter name="defaultPolicyFilter" desc="Filters for compatibility，license header policies">
<filteritem type="filepath" name=".*" desc="The files involved in compilation are the LGPL protocol.They are used in dynamic link mode."/>
</filefilter>
</filefilterlist>
</oatconfig>
</configuration>
README
+1
View File
@@ -0,0 +1 @@
See README.md
README.OpenSource
+10
View File
@@ -0,0 +1,10 @@
[
{
"Name": "glib",
"License": "LGPL V2.1",
"License File": "COPYING",
"Version Number": "2.62.5",
"Upstream URL": "https://www.gtk.org/",
"Description": "GLib is the low-level core library that forms the basis for projects such as GTK and GNOME. It provides data structure handling for C, portability wrappers, and interfaces for such runtime functionality as an event loop, threads, dynamic loading, and an object system."
}
]
README.en.md
-36
View File
@@ -1,36 +0,0 @@
# third_party_glib
#### Description
Third-party open-source software glib | 三方开源软件glib
#### Software Architecture
Software architecture description
#### Installation
1. xxxx
2. xxxx
3. xxxx
#### Instructions
1. xxxx
2. xxxx
3. xxxx
#### Contribution
1. Fork the repository
2. Create Feat_xxx branch
3. Commit your code
4. Create Pull Request
#### Gitee Feature
1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md
2. Gitee blog [blog.gitee.com](https://blog.gitee.com)
3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore)
4. The most valuable open source project [GVP](https://gitee.com/gvp)
5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help)
6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
README.md
+321 -25
View File
@@ -1,37 +1,333 @@
# third_party_glib
# GLib
#### 介绍
Third-party open-source software glib | 三方开源软件glib
GLib is the low-level core library that forms the basis for projects such
as GTK and GNOME. It provides data structure handling for C, portability
wrappers, and interfaces for such runtime functionality as an event loop,
threads, dynamic loading, and an object system.
#### 软件架构
软件架构说明
The official download locations are:
<https://download.gnome.org/sources/glib>
The official web site is:
<https://www.gtk.org/>
#### 安装教程
## Installation
1. xxxx
2. xxxx
3. xxxx
See the file '[INSTALL.in](INSTALL.in)'
#### 使用说明
## How to report bugs
1. xxxx
2. xxxx
3. xxxx
Bugs should be reported to the GNOME issue tracking system.
(<https://gitlab.gnome.org/GNOME/glib/issues/new>). You will need
to create an account for yourself.
#### 参与贡献
In the bug report please include:
1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request
* Information about your system. For instance:
* What operating system and version
* For Linux, what version of the C library
* And anything else you think is relevant.
* How to reproduce the bug.
* If you can reproduce it with one of the test programs that are built
in the tests/ subdirectory, that will be most convenient. Otherwise,
please include a short test program that exhibits the behavior.
As a last resort, you can also provide a pointer to a larger piece
of software that can be downloaded.
* If the bug was a crash, the exact text that was printed out
when the crash occured.
* Further information such as stack traces may be useful, but
is not necessary.
## Patches
#### 特技
Patches should also be submitted as merge requests to gitlab.gnome.org. If the
patch fixes an existing issue, please refer to the issue in your commit message
with the following notation (for issue 123):
Closes: #123
1. 使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2. Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3. 你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4. [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5. Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6. Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
Otherwise, create a new merge request that introduces the change, filing a
separate issue is not required.
## Notes
### Notes about GLib 2.48
* The system copy of PCRE is now used by default to implement GRegex.
Configure with --with-pcre=internal if a system PCRE version
is unavailable or undesired.
### Notes about GLib 2.46
* GTask no longer imposes a fixed limit on the number of tasks that
can be run_in_thread() simultaneously, since doing this inevitably
results in deadlocks in some use cases. Instead, it now has a base
number of threads that can be used "for free", but will gradually
add more threads to the pool if too much time passes without any
tasks completing.
The exact behavior may continue to change in the future, and it's
possible that some future version of GLib may not do any
rate-limiting at all. As a result, you should no longer assume that
GTask will rate-limit tasks itself (or, by extension, that calls to
certain async gio methods will automatically be rate-limited for
you). If you have a very large number of tasks to run, and don't
want them to all run at once, you should rate-limit them yourself.
### Notes about GLib 2.40
* g_test_run() no longer runs tests in exactly the order they are
registered; instead, it groups them according to test suites (ie,
path components) like the documentation always claimed it did. In
some cases, this can result in a sub-optimal ordering of tests,
relative to the old behavior. The fix is to change the test paths to
properly group together the tests that should run together. (eg, if
you want to run test_foo_simple(), test_bar_simple(), and
test_foo_using_bar() in that order, they should have test paths like
"/simple/foo", "/simple/bar", "/complex/foo-using-bar", not
"/foo/simple", "/bar/simple", "/foo/using-bar" (which would result
in test_foo_using_bar() running before test_bar_simple()).
(The behavior actually changed in GLib 2.36, but it was not
documented at the time, since we didn't realize it mattered.)
### Notes about GLib 2.36
* It is no longer necessary to call g_type_init(). If you are
loading GLib as a dynamic module, you should be careful to avoid
unloading it, then subsequently loading it again. This never
really worked before, but it is now explicitly undefined behavior.
Note that if g_type_init() was the only explicit use of a GObject
API and you are using linker flags such as --no-add-needed, then
you may have to artificially use some GObject call to keep the
linker from optimizing away -lgobject. We recommend to use
g_type_ensure (G_TYPE_OBJECT) for this purpose.
* This release contains an incompatible change to the g_get_home_dir()
function. Previously, this function would effectively ignore the HOME
environment variable and always return the value from /etc/password.
As of this version, the HOME variable is used if it is set and the
value from /etc/passwd is only used as a fallback.
* The 'flowinfo' and 'scope_id' fields of GInetSocketAddress
(introduced in GLib 2.32) have been fixed to be in host byte order
rather than network byte order. This is an incompatible change, but
the previous behavior was clearly broken, so it seems unlikely that
anyone was using it.
### Notes about GLib 2.34
* GIO now looks for thumbnails in XDG_CACHE_HOME, following a
recent alignment of the thumbnail spec with the basedir spec.
* The default values for GThreadPools max_unused_threads and
max_idle_time settings have been changed to 2 and 15*1000,
respectively.
### Notes about GLib 2.32
* It is no longer necessary to use g_thread_init() or to link against
libgthread. libglib is now always thread-enabled. Custom thread
system implementations are no longer supported (including errorcheck
mutexes).
* The thread and synchronisation APIs have been updated.
GMutex and GCond can be statically allocated without explicit
initialisation, as can new types GRWLock and GRecMutex. The
GStatic_______ variants of these types have been deprecated. GPrivate
can also be statically allocated and has a nicer API (deprecating
GStaticPrivate). Finally, g_thread_create() has been replaced with a
substantially simplified g_thread_new().
* The g_once_init_enter()/_leave() functions have been replaced with
macros that allow for a pointer to any gsize-sized object, not just a
gsize*. The assertions to ensure that a pointer to a correctly-sized
object is being used will not work with generic pointers (ie: (void*)
and (gpointer) casts) which would have worked with the old version.
* It is now mandatory to include glib.h instead of individual headers.
* The -uninstalled variants of the pkg-config files have been dropped.
* For a long time, gobject-2.0.pc mistakenly declared a public
dependency on gthread-2.0.pc (when the dependency should have been
private). This means that programs got away with calling
g_thread_init() without explicitly listing gthread-2.0.pc among their
dependencies.
gthread has now been removed as a gobject dependency, which will cause
such programs to break.
The fix for this problem is either to declare an explicit dependency
on gthread-2.0.pc (if you care about compatibility with older GLib
versions) or to stop calling g_thread_init().
* g_debug() output is no longer enabled by default. It can be enabled
on a per-domain basis with the G_MESSAGES_DEBUG environment variable
like
G_MESSAGES_DEBUG=domain1,domain2
or
G_MESSAGES_DEBUG=all
### Notes about GLib 2.30
* GObject includes a generic marshaller, g_cclosure_marshal_generic.
To use it, simply specify NULL as the marshaller in g_signal_new().
The generic marshaller is implemented with libffi, and consequently
GObject depends on libffi now.
### Notes about GLib 2.28
* The GApplication API has changed compared to the version that was
included in the 2.25 development snapshots. Existing users will need
adjustments.
### Notes about GLib 2.26
* Nothing noteworthy.
### Notes about GLib 2.24
* It is now allowed to call g_thread_init(NULL) multiple times, and
to call glib functions before g_thread_init(NULL) is called
(although the later is mainly a change in docs as this worked before
too). See the GThread reference documentation for the details.
* GObject now links to GThread and threads are enabled automatically
when g_type_init() is called.
* GObject no longer allows to call g_object_set() on construct-only properties
while an object is being initialized. If this behavior is needed, setting a
custom constructor that just chains up will re-enable this functionality.
* GMappedFile on an empty file now returns NULL for the contents instead of
returning an empty string. The documentation specifically states that code
may not rely on nul-termination here so any breakage caused by this change
is a bug in application code.
### Notes about GLib 2.22
* Repeated calls to g_simple_async_result_set_op_res_gpointer used
to leak the data. This has been fixed to always call the provided
destroy notify.
### Notes about GLib 2.20
* The functions for launching applications (e.g. g_app_info_launch() +
friends) now passes a FUSE file:// URI if possible (requires gvfs
with the FUSE daemon to be running and operational). With gvfs 2.26,
FUSE file:// URIs will be mapped back to gio URIs in the GFile
constructors. The intent of this change is to better integrate
POSIX-only applications, see bug #528670 for the rationale. The
only user-visible change is when an application needs to examine an
URI passed to it (e.g. as a positional parameter). Instead of
looking at the given URI, the application will now need to look at
the result of g_file_get_uri() after having constructed a GFile
object with the given URI.
### Notes about GLib 2.18
* The recommended way of using GLib has always been to only include the
toplevel headers glib.h, glib-object.h and gio.h. GLib enforces this by
generating an error when individual headers are directly included.
To help with the transition, the enforcement is not turned on by
default for GLib headers (it is turned on for GObject and GIO).
To turn it on, define the preprocessor symbol G_DISABLE_SINGLE_INCLUDES.
### Notes about GLib 2.16
* GLib now includes GIO, which adds optional dependencies against libattr
and libselinux for extended attribute and SELinux support. Use
--disable-xattr and --disable-selinux to build without these.
### Notes about GLib 2.10
* The functions g_snprintf() and g_vsnprintf() have been removed from
the gprintf.h header, since they are already declared in glib.h. This
doesn't break documented use of gprintf.h, but people have been known
to include gprintf.h without including glib.h.
* The Unicode support has been updated to Unicode 4.1. This adds several
new members to the GUnicodeBreakType enumeration.
* The support for Solaris threads has been retired. Solaris has provided
POSIX threads for long enough now to have them available on every
Solaris platform.
* 'make check' has been changed to validate translations by calling
msgfmt with the -c option. As a result, it may fail on systems with
older gettext implementations (GNU gettext < 0.14.1, or Solaris gettext).
'make check' will also fail on systems where the C compiler does not
support ELF visibility attributes.
* The GMemChunk API has been deprecated in favour of a new 'slice
allocator'. See the g_slice documentation for more details.
* A new type, GInitiallyUnowned, has been introduced, which is
intended to serve as a common implementation of the 'floating reference'
concept that is e.g. used by GtkObject. Note that changing the
inheritance hierarchy of a type can cause problems for language
bindings and other code which needs to work closely with the type
system. Therefore, switching to GInitiallyUnowned should be done
carefully. g_object_compat_control() has been added to GLib 2.8.5
to help with the transition.
### Notes about GLib 2.6.0
* GLib 2.6 introduces the concept of 'GLib filename encoding', which is the
on-disk encoding on Unix, but UTF-8 on Windows. All GLib functions
returning or accepting pathnames have been changed to expect
filenames in this encoding, and the common POSIX functions dealing
with pathnames have been wrapped. These wrappers are declared in the
header <glib/gstdio.h> which must be included explicitly; it is not
included through <glib.h>.
On current (NT-based) Windows versions, where the on-disk file names
are Unicode, these wrappers use the wide-character API in the C
library. Thus applications can handle file names containing any
Unicode characters through GLib's own API and its POSIX wrappers,
not just file names restricted to characters in the system codepage.
To keep binary compatibility with applications compiled against
older versions of GLib, the Windows DLL still provides entry points
with the old semantics using the old names, and applications
compiled against GLib 2.6 will actually use new names for the
functions. This is transparent to the programmer.
When compiling against GLib 2.6, applications intended to be
portable to Windows must take the UTF-8 file name encoding into
consideration, and use the gstdio wrappers to access files whose
names have been constructed from strings returned from GLib.
* Likewise, g_get_user_name() and g_get_real_name() have been changed
to return UTF-8 on Windows, while keeping the old semantics for
applications compiled against older versions of GLib.
* The GLib uses an '_' prefix to indicate private symbols that
must not be used by applications. On some platforms, symbols beginning
with prefixes such as _g will be exported from the library, on others not.
In no case can applications use these private symbols. In addition to that,
GLib+ 2.6 makes several symbols private which were not in any installed
header files and were never intended to be exported.
* To reduce code size and improve efficiency, GLib, when compiled
with the GNU toolchain, has separate internal and external entry
points for exported functions. The internal names, which begin with
IA__, may be seen when debugging a GLib program.
* On Windows, GLib no longer opens a console window when printing
warning messages if stdout or stderr are invalid, as they are in
"Windows subsystem" (GUI) applications. Simply redirect stdout or
stderr if you need to see them.
* The child watch functionality tends to reveal a bug in many
thread implementations (in particular the older LinuxThreads
implementation on Linux) where it's not possible to call waitpid()
for a child created in a different thread. For this reason, for
maximum portability, you should structure your code to fork all
child processes that you want to wait for from the main thread.
* A problem was recently discovered with g_signal_connect_object();
it doesn't actually disconnect the signal handler once the object being
connected to dies, just disables it. See the API docs for the function
for further details and the correct workaround that will continue to
work with future versions of GLib.
README.rationale
+10
View File
@@ -0,0 +1,10 @@
This file documents various major decisions which affect GLib development,
giving a brief rationale of each decision, plus a link to further discussion.
* Compiler attributes: https://bugzilla.gnome.org/show_bug.cgi?id=113075#c46
GLib uses GIR annotations instead of compiler attributes. They are tidier,
already supported by GLib and GNOME tools, and accomplish the same task as
compiler attributes. GLib does not provide macros for attributes like
nonnull because it would not use them.
README.win32
+1
View File
@@ -0,0 +1 @@
See README.win32.md
README.win32.md
+182
View File
@@ -0,0 +1,182 @@
Chun-wei Fan `<fanc999@yahoo.com.tw>`
Philip Withnall `<withnall@endlessm.com>`
Nirbheek Chauhan `<nirbheek@centricular.com>`
This document was last updated in 2019. You're reading this in the future, and
lots of information might be misleading or outdated in your age. You have been
warned.
# General
For prebuilt binaries (DLLs and EXEs) and developer packages (headers,
import libraries) of GLib, Pango, GTK+ etc for Windows, go to
https://www.gtk.org/download/windows.php . They are for "native"
Windows meaning they use the Win32 API and Microsoft C runtime library
only. No POSIX (Unix) emulation layer like Cygwin is involved.
To build GLib on Win32, you can use either GCC ("MinGW") or the Microsoft
Visual Studio toolchain. For the latter, Visual Studio 2015 and later are
recommended. For older Visual Studio versions, see below.
You can also cross-compile GLib for Windows from Linux using the
cross-compiling mingw packages for your distro.
Note that to just *use* GLib on Windows, there is no need to build it
yourself.
On Windows setting up a correct build environment is very similar to typing
`meson; ninja` like on Linux.
The following preprocessor macros are to be used for conditional
compilation related to Win32 in GLib-using code:
- `G_OS_WIN32` is defined when compiling for native Win32, without
any POSIX emulation, other than to the extent provided by the
bundled Microsoft C library.
- `G_WITH_CYGWIN` is defined if compiling for the Cygwin
environment. Note that `G_OS_WIN32` is *not* defined in that case, as
Cygwin is supposed to behave like Unix. `G_OS_UNIX` *is* defined by a GLib
for Cygwin.
- `G_PLATFORM_WIN32` is defined when either `G_OS_WIN32` or `G_WITH_CYGWIN`
is defined.
These macros are defined in `glibconfig.h`, and are thus available in
all source files that include `<glib.h>`.
Additionally, there are the compiler-specific macros:
- `__GNUC__` is defined when using GCC or Clang
- `__clang__` is defined when using Clang or Clang-CL
- `_MSC_VER` is defined when using MSVC or Clang-CL
`G_OS_WIN32` implies using the Microsoft C runtime, which used to be
`msvcrt.dll` and is now the [Universal CRT](https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-library-features?view=vs-2015)
when building with Visual Studio. When using the MinGW-GCC toolchain, the CRT
in use depends on the settings used while the toolchain was built. We highly
recommend [using the Universal CRT when building with
MinGW](https://mingwpy.github.io/ucrt.html) too.
GLib is not actively tested with the static versions of the UCRT, but if you
need to use those, patches are welcome.
# Building software that use GLib or GTK+
Building software that just *uses* GLib or GTK+ also require to have
the right compiler set up the right way. If you intend to use MinGW-GCC,
follow the relevant instructions below in that case, too.
You should link to GLib using the `-mms-bitfields` GCC flag. This flag means
that the struct layout rules are identical to those used by MSVC. This is
essential if the same DLLs are to be usable both from gcc- and MSVC-compiled
code.
## Cross-CRT issues
You should take care that the DLLs that your code links to are using the same
C runtime library. Not doing so can and likely will lead to panics and crashes
**unless** you're very careful while passing objects allocated by a library
linked with one CRT to a library linked to another CRT, or (more commonly) not
doing that at all.
If you *do* pass CRT objects across CRT boundaries, do not file any issues
about whatever happens next.
To give an example, opening a `FILE` handle created by one CRT cannot be
understood by any other CRT, and will lead to an access violation. You also
cannot allocate memory in one CRT and free it using another.
There are [many other cases where you must not allow objects to cross CRT boundaries](https://docs.microsoft.com/en-us/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries?view=vs-2019),
but in theory if you're **very very** careful, you can make things work. Again,
please do not come to us for help if you choose to do this.
# Building GLib
You can build GLib with MinGW-GCC, MSVC, or (experimentally) with Clang-CL.
For all compilers, you will need the following:
- Install Python 3.6.x or newer, either 32-bit or 64-bit. We recommend enabling
the option to add it to your `PATH`.
- [Install Meson](https://mesonbuild.com/Getting-meson.html)
- Install the [Ninja build tool](https://github.com/ninja-build/ninja/releases), which can also be
installed with `pip3`. You can skip this step if you want to generate Visual
Studio project files.
- [git for Windows](https://gitforwindows.org/) is required, since Meson makes
use of git to download dependencies using subprojects.
## Building with MinGW-GCC
Open your MSYS or [MSYS2](https://www.msys2.org/) shell where you have the
MinGW-GCC toolchain installed, and build GLib [like any other Meson
project](https://mesonbuild.com/Quick-guide.html#compiling-a-meson-project).
## Building with Visual Studio 2015 or newer
Meson is now the only supported method of building GLib using Visual Studio.
To do a build using Meson, do the following:
- Open a Visual Studio (or SDK) command prompt that matches the Visual Studio
version and build platform (Win32/x86, x64, etc.) that will be used in all
the following steps.
- Create an empty directory/folder for the build inside your GLib sources
directory, say, `_builddir`, and `cd` into it.
- Set up the build using Meson:
```cmd
> meson .. --buildtype=<release|debug|debugoptimized> --prefix=<path> [--backend=vs]
```
Please see [the Meson docs](https://mesonbuild.com/Builtin-options.html#core-options)
for an explanation for `--buildtype`.
The path passed for `--prefix` need not to be on the same drive as where the
build is carried out, but it is recommended to use forward slashes for this
path. The `--backend=vs` option can be used if the Visual Studio project
generator is preferred over using Ninja.
- Build, test and install the build:
Run `ninja` to build, `meson test` to test and `meson install` to install the
build. If you used `--backend=vs`, instead of running `ninja`, you need to
use `msbuild` or you can open the generated solution in Visual Studio.
## Building with old versions of Visual Studio
The steps are the same as above, with the following notes about issues that you might face.
### C4819 build errors
If you are building GLib-based libraries or applications, or GLib itself
and you see a `C4819` error (or warning, before `C4819` is treated as an error
in `msvc_recommended_pragmas.h`), please be advised that this error/warning should
not be disregarded, as this likely means portions of the build are not being
done correctly, as this is an issue of Visual Studio running on CJK (East Asian)
locales. This is an issue that also affects builds of other projects, such as
QT, Firefox, LibreOffice/OpenOffice, Pango and GTK, along with many other projects.
To overcome this problem, please set your system's locale setting for non-Unicode to
English (United States), reboot, and restart the build, and the code should build
normally.
### Visual Studio 2008 hacks
- You need to run the following lines from your build directory, to embed the
manifests that are generated during the build, assuming the built binaries
are installed to `$(PREFIX)`, after a successful build/installation:
```cmd
> for /r %f in (*.dll.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;2
> for /r %f in (*.exe.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;1
```
- If building for amd64/x86_64/x64, sometimes the compilation of sources may seem to hang, which
is caused by an optimization issue in the 2008 x64 compiler. You need to use Task Manager to
remove all running instances of `cl.exe`, which will cause the build process to terminate. Update
the build flags of the sources that hang on compilation by changing its `"/O2"` flag to `"/O1"`
in `build.ninja`, and retry the build, where things should continue to build normally. At the
time of writing, this is needed for compiling `glib/gtestutils.c`, `gio/gsettings.c`,
`gio/gsettingsschema.c` and `gio/tests/gsubprocess-testprog.c`
check-abis.sh
Executable
+23
View File
@@ -0,0 +1,23 @@
#!/bin/sh -e
list_leaked_symbols () {
nm -D "$1" | grep ' T ' | cut -f 3 -d ' ' | egrep -v "$2"
}
check_symbols () {
if [ "`list_leaked_symbols "$1" "$2" | wc -l`" -ne 0 ]; then
echo File "$1" possibly leaking symbols:
list_leaked_symbols "$1" "$2"
exit 1
fi
}
allowed="^_init$|^_fini$|^_ftext$|^g_"
allowed_in_libglib="${allowed}|^glib__private__$|^glib_gettext$|^glib_pgettext$|^glib_check_version$"
allowed_in_libgthread='^_init$|^_fini$|^_ftext$|^g_thread_init$|^g_thread_init_with_errorcheck_mutexes$'
check_symbols glib/.libs/libglib-2.0.so "$allowed_in_libglib"
check_symbols gthread/.libs/libgthread-2.0.so "$allowed_in_libgthread"
for file in gmodule/.libs/libgmodule-2.0.so gobject/.libs/libgobject-2.0.so gio/.libs/libgio-2.0.so; do
check_symbols "$file" "$allowed"
done
config.h
Executable
+513
View File
@@ -0,0 +1,513 @@
/*
* Autogenerated by the Meson build system.
* Do not edit, your changes will be lost.
*/
#pragma once
#define ALIGNOF_GUINT32 4
#define ALIGNOF_GUINT64 8
#ifdef __LP64__
#define ALIGNOF_UNSIGNED_LONG 8
#define DBL_EXPBIT0_BIT 20
#define DBL_EXPBIT0_WORD 1
#else
#define ALIGNOF_UNSIGNED_LONG 4
#endif
#define EXEEXT
#define GETTEXT_PACKAGE "glib20"
#define GLIB_BINARY_AGE 6205
#define GLIB_INTERFACE_AGE 0
#define GLIB_LOCALE_DIR "/usr/local/share/locale"
#define GLIB_MAJOR_VERSION 2
#define GLIB_MICRO_VERSION 5
#define GLIB_MINOR_VERSION 62
#define G_VA_COPY va_copy
#define HAVE_ALLOCA_H 1
#define HAVE_BIND_TEXTDOMAIN_CODESET
#undef HAVE_C99_SNPRINTF
#undef HAVE_C99_VSNPRINTF
#define HAVE_CLOCK_GETTIME 1
#define HAVE_CODESET 1
#define HAVE_DCGETTEXT 1
#define HAVE_DIRENT_H 1
#define HAVE_ENDMNTENT 1
#define HAVE_ENDSERVENT 1
#define HAVE_EVENTFD 1
#define HAVE_FALLOCATE 1
#define HAVE_FCHMOD 1
#define HAVE_FCHOWN 1
#define HAVE_FLOAT_H 1
#define HAVE_FSYNC 1
#define HAVE_FUTEX 1
#define HAVE_GETAUXVAL 1
#define HAVE_GETC_UNLOCKED 1
#define HAVE_GETGRGID_R 1
#define HAVE_GETMNTENT_R 1
#define HAVE_GETPWUID_R 1
#define HAVE_GETRESUID 1
#define HAVE_GETTEXT 1
#define HAVE_GMTIME_R 1
#define HAVE_GRP_H 1
#define HAVE_HASMNTOPT 1
#define HAVE_IF_INDEXTONAME 1
#define HAVE_IF_NAMETOINDEX 1
#define HAVE_INOTIFY_INIT1 1
#define HAVE_INTMAX_T 1
#define HAVE_INTTYPES_H 1
#define HAVE_INTTYPES_H_WITH_UINTMAX 1
#define HAVE_IP_MREQN 1
#define HAVE_LANGINFO_CODESET 1
#define HAVE_LANGINFO_TIME 1
#define HAVE_LCHOWN 1
#define HAVE_LC_MESSAGES 1
#define HAVE_LIMITS_H 1
#define HAVE_LINK 1
#define HAVE_LINUX_MAGIC_H 1
#define HAVE_LOCALE_H 1
#define HAVE_LOCALTIME_R 1
#define HAVE_LONG_DOUBLE 1
#define HAVE_LONG_LONG 1
#define HAVE_LSTAT 1
#define HAVE_MALLOC_H 1
#define HAVE_MBRTOWC 1
#define HAVE_MEMALIGN 1
#define HAVE_MEMORY_H 1
#define HAVE_MMAP 1
#define HAVE_MNTENT_H 1
#define HAVE_NETLINK 1
#define HAVE_NEWLOCALE 1
#define HAVE_OPEN_O_DIRECTORY 1
#define HAVE_PIPE2 1
#define HAVE_POLL 1
#define HAVE_POLL_H 1
#define HAVE_POSIX_MEMALIGN 1
#define HAVE_POSIX_SPAWN 1
#define HAVE_PRLIMIT 1
#undef HAVE_PROC_SELF_CMDLINE
#define HAVE_PTHREAD_ATTR_SETINHERITSCHED 1
#define HAVE_PTHREAD_ATTR_SETSTACKSIZE 1
#define HAVE_PTHREAD_CONDATTR_SETCLOCK 1
#define HAVE_PTHREAD_GETNAME_NP 1
#define HAVE_PTHREAD_SETNAME_NP_WITH_TID 1
#define HAVE_PTRDIFF_T 1
#define HAVE_PWD_H 1
#define HAVE_READLINK 1
#define HAVE_RECVMMSG 1
#define HAVE_RES_INIT 1
#define HAVE_RTLD_GLOBAL 1
#define HAVE_RTLD_LAZY 1
#define HAVE_RTLD_NEXT 1
#define HAVE_RTLD_NOW 1
#define HAVE_SCHED_H 1
#define HAVE_SENDMMSG 1
#define HAVE_SETENV 1
#define HAVE_SETMNTENT 1
#define HAVE_SIG_ATOMIC_T 1
#define HAVE_SIOCGIFADDR /**/
#define HAVE_SNPRINTF 1
#define HAVE_SPAWN_H 1
#define HAVE_SPLICE 1
#define HAVE_STATFS 1
#define HAVE_STATVFS 1
#define HAVE_STDINT_H 1
#define HAVE_STDINT_H_WITH_UINTMAX 1
#define HAVE_STDLIB_H 1
#define HAVE_STPCPY 1
#define HAVE_STRCASECMP 1
#define HAVE_STRERROR_R 1
#define HAVE_STRINGS_H 1
#define HAVE_STRING_H 1
#define HAVE_STRNCASECMP 1
#define HAVE_STRNLEN 1
#define HAVE_STRSIGNAL 1
#define HAVE_STRTOD_L 1
#define HAVE_STRTOLL_L 1
#define HAVE_STRTOULL_L 1
#define HAVE_STRUCT_DIRENT_D_TYPE 1
#define HAVE_STRUCT_STATFS_F_BAVAIL 1
#define HAVE_STRUCT_STAT_ST_ATIMENSEC 1
#define HAVE_STRUCT_STAT_ST_ATIM_TV_NSEC 1
#define HAVE_STRUCT_STAT_ST_BLKSIZE 1
#define HAVE_STRUCT_STAT_ST_BLOCKS 1
#define HAVE_STRUCT_STAT_ST_CTIMENSEC 1
#define HAVE_STRUCT_STAT_ST_CTIM_TV_NSEC 1
#define HAVE_STRUCT_STAT_ST_MTIMENSEC 1
#define HAVE_STRUCT_STAT_ST_MTIM_TV_NSEC 1
#define HAVE_STRUCT_TM_TM_GMTOFF 1
#define HAVE_SYMLINK 1
#define HAVE_SYS_AUXV_H 1
#define HAVE_SYS_INOTIFY_H 1
#define HAVE_SYS_MOUNT_H 1
#define HAVE_SYS_PARAM_H 1
#define HAVE_SYS_RESOURCE_H 1
#define HAVE_SYS_SCHED_GETATTR 1
#define HAVE_SYS_SELECT_H 1
#define HAVE_SYS_STATFS_H 1
#define HAVE_SYS_STATVFS_H 1
#define HAVE_SYS_STAT_H 1
#define HAVE_SYS_TIMES_H 1
#define HAVE_SYS_TIME_H 1
#define HAVE_SYS_TYPES_H 1
#define HAVE_SYS_UIO_H 1
#define HAVE_SYS_VFS_H 1
#define HAVE_SYS_WAIT_H 1
#define HAVE_SYS_XATTR_H 1
#define HAVE_TERMIOS_H 1
#define HAVE_TIMEGM 1
#define HAVE_UNISTD_H 1
#undef HAVE_UNIX98_PRINTF
#define HAVE_UNSETENV 1
#define HAVE_USELOCALE 1
#define HAVE_UTIMES 1
#define HAVE_VASPRINTF 1
#define HAVE_VSNPRINTF 1
#define HAVE_WCHAR_H 1
#define HAVE_WCHAR_T 1
#define HAVE_WCRTOMB 1
#define HAVE_WCSLEN 1
#define HAVE_WCSNLEN 1
#define HAVE_WINT_T 1
#define HAVE_XATTR 1
#define HAVE_XLOCALE_H 1
#define MAJOR_IN_SYSMACROS 1
#define NEED_PRINTF_DIRECTIVE_A 1
#define NEED_PRINTF_DIRECTIVE_F 1
#define NEED_PRINTF_DOUBLE 1
#define NEED_PRINTF_ENOMEM 1
#define NEED_PRINTF_FLAG_ZERO 1
#define NEED_PRINTF_INFINITE_DOUBLE 1
#define NEED_PRINTF_LONG_DOUBLE 1
#define PACKAGE_BUGREPORT "https://gitlab.gnome.org/GNOME/glib/issues/new"
#define PACKAGE_NAME "glib"
#define PACKAGE_STRING "glib 2.63.6"
#define PACKAGE_TARNAME "glib"
#define PACKAGE_URL ""
#define PACKAGE_VERSION "2.63.6"
#define SIZEOF_CHAR 1
#define SIZEOF_INT 4
#ifdef __LP64__
#define SIZEOF_LONG 8
#else
#define SIZEOF_LONG 4
#endif
#define SIZEOF_LONG_LONG 8
#define SIZEOF_SHORT 2
#ifdef __LP64__
#define SIZEOF_SIZE_T 8
#define SIZEOF_SSIZE_T 8
#define SIZEOF_VOID_P 8
#else
#define SIZEOF_SIZE_T 4
#define SIZEOF_SSIZE_T 4
#define SIZEOF_VOID_P 4
#endif
#define SIZEOF_WCHAR_T 4
#define STATFS_ARGS 2
/* Defined if strerror_r returns char * */
#define STRERROR_R_CHAR_P 1
#define THREADS_POSIX 1
#define USE_STATFS 1
#undef USE_SYSTEM_PCRE
#define USE_SYSTEM_PRINTF
#define _GLIB_EXTERN __attribute__((visibility("default"))) extern
#define _GNU_SOURCE 1
#define gl_extern_inline
/* Please see the Gnulib manual for how to use these macros.
Suppress extern inline with HP-UX cc, as it appears to be broken; see
<https://lists.gnu.org/r/bug-texinfo/2013-02/msg00030.html>.
Suppress extern inline with Sun C in standards-conformance mode, as it
mishandles inline functions that call each other. E.g., for 'inline void f
(void) { } inline void g (void) { f (); }', c99 incorrectly complains
'reference to static identifier "f" in extern inline function'.
This bug was observed with Sun C 5.12 SunOS_i386 2011/11/16.
Suppress extern inline (with or without __attribute__ ((__gnu_inline__)))
on configurations that mistakenly use 'static inline' to implement
functions or macros in standard C headers like <ctype.h>. For example,
if isdigit is mistakenly implemented via a static inline function,
a program containing an extern inline function that calls isdigit
may not work since the C standard prohibits extern inline functions
from calling static functions. This bug is known to occur on:
OS X 10.8 and earlier; see:
https://lists.gnu.org/r/bug-gnulib/2012-12/msg00023.html
DragonFly; see
http://muscles.dragonflybsd.org/bulk/bleeding-edge-potential/latest-per-pkg/ah-tty-0.3.12.log
FreeBSD; see:
https://lists.gnu.org/r/bug-gnulib/2014-07/msg00104.html
OS X 10.9 has a macro __header_inline indicating the bug is fixed for C and
for clang but remains for g++; see <https://trac.macports.org/ticket/41033>.
Assume DragonFly and FreeBSD will be similar. */
#if (((defined __APPLE__ && defined __MACH__) \
|| defined __DragonFly__ || defined __FreeBSD__) \
&& (defined __header_inline \
? (defined __cplusplus && defined __GNUC_STDC_INLINE__ \
&& ! defined __clang__) \
: ((! defined _DONT_USE_CTYPE_INLINE_ \
&& (defined __GNUC__ || defined __cplusplus)) \
|| (defined _FORTIFY_SOURCE && 0 < _FORTIFY_SOURCE \
&& defined __GNUC__ && ! defined __cplusplus))))
# define _GL_EXTERN_INLINE_STDHEADER_BUG
#endif
#if ((__GNUC__ \
? defined __GNUC_STDC_INLINE__ && __GNUC_STDC_INLINE__ \
: (199901L <= __STDC_VERSION__ \
&& !defined __HP_cc \
&& !defined __PGI \
&& !(defined __SUNPRO_C && __STDC__))) \
&& !defined _GL_EXTERN_INLINE_STDHEADER_BUG)
# define _GL_INLINE inline
# define _GL_EXTERN_INLINE extern inline
# define _GL_EXTERN_INLINE_IN_USE
#elif (2 < __GNUC__ + (7 <= __GNUC_MINOR__) && !defined __STRICT_ANSI__ \
&& !defined _GL_EXTERN_INLINE_STDHEADER_BUG)
# if defined __GNUC_GNU_INLINE__ && __GNUC_GNU_INLINE__
/* __gnu_inline__ suppresses a GCC 4.2 diagnostic. */
# define _GL_INLINE extern inline __attribute__ ((__gnu_inline__)) __attribute__ ((always_inline))
# else
# define _GL_INLINE extern inline
# endif
# define _GL_EXTERN_INLINE extern
# define _GL_EXTERN_INLINE_IN_USE
#else
# define _GL_INLINE static _GL_UNUSED
# define _GL_EXTERN_INLINE static _GL_UNUSED
#endif
/* In GCC 4.6 (inclusive) to 5.1 (exclusive),
suppress bogus "no previous prototype for 'FOO'"
and "no previous declaration for 'FOO'" diagnostics,
when FOO is an inline function in the header; see
<https://gcc.gnu.org/bugzilla/show_bug.cgi?id=54113> and
<https://gcc.gnu.org/bugzilla/show_bug.cgi?id=63877>. */
#if __GNUC__ == 4 && 6 <= __GNUC_MINOR__
# if defined __GNUC_STDC_INLINE__ && __GNUC_STDC_INLINE__
# define _GL_INLINE_HEADER_CONST_PRAGMA
# else
# define _GL_INLINE_HEADER_CONST_PRAGMA \
_Pragma ("GCC diagnostic ignored \"-Wsuggest-attribute=const\"")
# endif
# define _GL_INLINE_HEADER_BEGIN \
_Pragma ("GCC diagnostic push") \
_Pragma ("GCC diagnostic ignored \"-Wmissing-prototypes\"") \
_Pragma ("GCC diagnostic ignored \"-Wmissing-declarations\"") \
_GL_INLINE_HEADER_CONST_PRAGMA
# define _GL_INLINE_HEADER_END \
_Pragma ("GCC diagnostic pop")
#else
# define _GL_INLINE_HEADER_BEGIN
# define _GL_INLINE_HEADER_END
#endif
#define gl_unused
/* Define as a marker that can be attached to declarations that might not
be used. This helps to reduce warnings, such as from
GCC -Wunused-parameter. */
#if __GNUC__ >= 3 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 7)
# define _GL_UNUSED __attribute__ ((__unused__))
#else
# define _GL_UNUSED
#endif
docs/CODEOWNERS
+83
View File
@@ -0,0 +1,83 @@
# These are the people responsible for subsystems in GLib; if you're opening
# a merge request for files listed here, please add the following people to
# the list of reviewers
# The syntax of this file is defined by GitLab:
# https://docs.gitlab.com/ee/user/project/code_owners.html
# Which, in turn, is similar to the .gitignore and .gitattributes files:
#
# - comments start with `#`
# - the first column contains paths and globs
# - the second column contains GitLab user names or email addresses,
# separated by spaces
#
# The last matching glob (rather than the union of *all* matching globs) gives
# the owners of a piece of code.
#
# If you want to be responsible for code reviews in specific sections of
# the GLib code base, add yourself here.
# Overall maintainers
* @pwithnall @ebassi
# Build system
meson.build @xclaesse @nirbheek @pwithnall
meson_options.txt @xclaesse @nirbheek @pwithnall
subprojects/ @xclaesse @nirbheek @pwithnall
# CI integration
.gitlab-ci* @pwithnall @xclaesse @creiter
# macOS support
*osx* @jralls @pwithnall @sdroege
*.m @jralls @pwithnall @sdroege
# Windows support
*win32* @lrn @creiter @fanc999 @pwithnall @sdroege @nirbheek
# Windows support (MSVC-specific)
*msvc* @fanc999 @creiter @pwithnall @sdroege @nirbheek
# Windows support (UWP-specific)
*uwp* @nirbheek
# Android support
*android* @xclaesse @pwithnall @sdroege
# BSD support
*bsd* @jmatthew @ajacoutot @lantw @pwithnall
*kqueue* @jmatthew @ajacoutot @lantw @pwithnall
# flatpak portals
gio/*portal* @matthiasc @alexl @pwithnall
# Networking
gio/g*{tcp,udp,tls,socket,resolver,proxy,network,inet,datagram}* @mcatanzaro @pgriffis @pwithnall @sdroege
# D-Bus
gio/g*bus* @smcv @pwithnall
# I/O
gio/g*{file,vfs,mount,drive,volume}* @oholy @alexl @pwithnall @sdroege
gio/g*stream* @alexl @pwithnall @sdroege
gio/gio-tool* @oholy @alexl @pwithnall
# Generic bits of GLib
glib/ @ebassi @pwithnall @sdroege
# GObject type system
gobject/ @ebassi @pwithnall @sdroege
# GVariant
glib/gvariant* @pwithnall @sdroege
# grefcount, GRcBox and GRefString
glib/gref{count,string}.[ch] @ebassi @pwithnall @sdroege
glib/grc*.[ch] @ebassi @pwithnall @sdroege
glib/garc*.[ch] @ebassi @pwithnall @sdroege
# Logging
glib/gmessages.[ch] @pwithnall @sdroege
# Google clusterfuzz support
fuzzing/ @pwithnall
docs/debugging.txt
+38
View File
@@ -0,0 +1,38 @@
Traps (G_BREAKPOINT) and traces for the debuging
================================================
Some code portions contain trap variables that can be set during
debugging time if G_ENABLE_DEBUG has been defined upon compilation
(use the --buildtype=debug option to configure for this, macros.txt
covers more details).
Such traps lead to immediate code halts to examine the current
program state and backtrace.
Currently, the following trap variables exist:
static volatile gulong g_trap_free_size;
static volatile gulong g_trap_realloc_size;
static volatile gulong g_trap_malloc_size;
If set to a size > 0, g_free(), g_realloc() and g_malloc()
respectively, will be intercepted if the size matches the
size of the corresponding memory block to free/reallocate/allocate.
This will only work with g_mem_set_vtable (glib_mem_profiler_table)
upon startup though, because memory profiling is required to match
on the memory block sizes.
static volatile GObject *g_trap_object_ref;
If set to a valid object pointer, ref/unref will be intercepted
with G_BREAKPOINT ();
static volatile gpointer *g_trap_instance_signals;
static volatile gpointer *g_trace_instance_signals;
If set to a valid instance pointer, debugging messages
will be spewed about emissions of signals on this instance.
For g_trap_instance_signals matches, the emissions will
also be intercepted with G_BREAKPOINT ();
Environment variables for debugging
===================================
When G_ENABLE_DEBUG was defined upon compilation, the GObject library
supports an environment variable GOBJECT_DEBUG that can be set to a
combination of the flags passed in to g_type_init() (currently
"objects" and "signals") to trigger debugging messages about
object bookkeeping and signal emissions during runtime.
docs/macros.txt
+53
View File
@@ -0,0 +1,53 @@
GLib's configure options and corresponding macros
=================================================
--buildtype={plain,release,minsize,custom}
none
--buildtype={debug,debugoptimized} [debugoptimized is the default]
-DG_ENABLE_DEBUG -g
Available to define yourself:
-DG_DISABLE_ASSERT -DG_DISABLE_CHECKS
Besides these, there are some local feature specific options, but my main
focus here is to concentrate on macros that affect overall GLib behaviour
and/or third party code.
Notes on GLib's internal and global macros
==========================================
G_DISABLE_ASSERT
The g_assert() and g_assert_not_reached() become non-functional
with this define. The motivation is to speed up end-user apps by
avoiding expensive checks.
This macro can affect third-party code. Defining it when building GLib
will only disable the assertion macros for GLib itself, but third-party code
that passes -DG_DISABLE_ASSERT to the compiler upon its own build
will end up with the non-functional variants after including glib.h
as well.
NOTE: Code inside the assertion macros should not have side effects
that affect the operation of the program.
G_DISABLE_CHECKS
This macro is similar to G_DISABLE_ASSERT, it affects third-party
code as mentioned above and the NOTE about G_DISABLE_ASSERT applies
too. The macros that become non-functional here are
g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
g_return_val_if_reached().
Additionally the glib_mem_profiler_table and g_mem_profile() from
gmem.h become non-functional if this macro is supplied.
This macro also switches off certain checks in the GSignal code.
G_ENABLE_DEBUG
Quite a bit of additional debugging code is compiled into GLib for this
macro, and since it is a globally visible define, third-party code may
be affected by it similar to G_DISABLE_ASSERT.
The additional code executed/compiled for this macro currently involve:
- extra validity checks for GDate
- memory profiling traps in gmem.c (consult debugging.txt for details)
- BREAKPOINT abortion for fatal log levels in gmessage.c instead of
plain abort() to allow debuggers trapping and overriding them
- added verbosity of gscanner.c to catch deprecated code paths
- added verbosity of gutils.c to catch deprecated code paths
- object ref/unref traps (consult debugging.txt) and object bookkeeping
in gobject.c
- extra validity checks in gsignal.c
docs/reference/.gitignore
+16
View File
@@ -0,0 +1,16 @@
*-decl-list.txt
*-decl.txt
*-unused.txt
*-undocumented.txt
*-undeclared.txt
*.args
*.hierarchy
*.interfaces
*.prerequisites
*.signals
*.stamp
html
xml
*.bak
version.xml
*.1
docs/reference/AUTHORS
+7
View File
@@ -0,0 +1,7 @@
Damon Chaplin <damon@karuna.freeserve.co.uk> and others.
See:
http://www.gtk.org/rdp/status.html
for a complete list.
docs/reference/COPYING
+30
View File
@@ -0,0 +1,30 @@
This work may be reproduced and distributed in whole or in part, in
any medium, physical or electronic, so as long as this copyright
notice remains intact and unchanged on all copies. Commercial
redistribution is permitted and encouraged, but you may not
redistribute, in whole or in part, under terms more restrictive than
those under which you received it. If you redistribute a modified or
translated version of this work, you must also make the source code to
the modified or translated version available in electronic form
without charge. However, mere aggregation as part of a larger work
shall not count as a modification for this purpose.
All code examples in this work are placed into the public domain,
and may be used, modified and redistributed without restriction.
BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
docs/reference/NEWS
View File
docs/reference/gio/.gitignore
+3
View File
@@ -0,0 +1,3 @@
*.1
gio-overrides.txt
tmpl
docs/reference/gio/concat-files-helper.py
+31
View File
@@ -0,0 +1,31 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Copyright (C) 2018 Collabora Inc.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General
# Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
#
# Author: Xavier Claessens <xavier.claessens@collabora.com>
import sys
if len(sys.argv) < 3:
print('Usage: {} <output file> <input file 1> ...'.format(os.path.basename(sys.argv[0])))
sys.exit(1)
with open(sys.argv[1], 'w') as outfile:
for fname in sys.argv[2:]:
with open(fname) as infile:
for line in infile:
outfile.write(line)
docs/reference/gio/gapplication.xml
+352
View File
@@ -0,0 +1,352 @@
<refentry id="gapplication-tool" lang="en">
<refentryinfo>
<title>gapplication</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gapplication</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gapplication</refname>
<refpurpose>D-Bus application launcher</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">version</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">list-apps</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">launch</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">launch</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">list-actions</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">action</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="plain"><replaceable>ACTION</replaceable></arg>
<arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gapplication</command> is a commandline implementation of the client-side of the
<interfacename>org.freedesktop.Application</interfacename> interface as specified by the freedesktop.org
Desktop Entry Specification.
</para>
<para>
<command>gapplication</command> can be used to start applications that have
<varname>DBusActivatable</varname> set to <literal>true</literal> in their <filename>.desktop</filename>
files and can be used to send messages to already-running instances of other applications.
</para>
<para>
It is possible for applications to refer to <command>gapplication</command> in the <varname>Exec</varname>
line of their <filename class='extension'>.desktop</filename> file to maintain backwards compatibility
with implementations that do not directly support <varname>DBusActivatable</varname>.
</para>
<para>
<command>gapplication</command> ships as part of <application>GLib</application>.
</para>
</refsect1>
<refsect1>
<title>Commands</title>
<refsect2>
<title>Global commands</title>
<variablelist>
<varlistentry>
<term>
<command>help</command>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</term>
<listitem>
<para>
Displays a short synopsis of the available commands or provides detailed help on a specific
command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>version</command>
</term>
<listitem>
<para>
Prints the GLib version whence <command>gapplication</command> came.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list-apps</command>
</term>
<listitem>
<para>
Prints a list of all application IDs that are known to support D-Bus activation. This list is
generated by scanning <filename class='extension'>.desktop</filename> files as per the current
<envar>XDG_DATA_DIRS</envar>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>launch</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
</term>
<listitem>
<para>
Launches an application.
</para>
<para>
The first parameter is the application ID in the familiar "reverse DNS" style (eg:
'<literal>org.gnome.app</literal>') without the <filename class='extension'>.desktop</filename>
suffix.
</para>
<para>
Optionally, if additional parameters are given, they are treated as the names of files to open and
may be filenames or URIs. If no files are given then the application is simply activated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list-actions</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</term>
<listitem>
<para>
List the actions declared in the application's <filename class='extension'>.desktop</filename>
file. The parameter is the application ID, as above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>action</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="plain"><replaceable>ACTION</replaceable></arg>
<arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
</term>
<listitem>
<para>
Invokes the named action (in the same way as would occur when activating an action specified in
the <filename class='extension'>.desktop</filename> file).
</para>
<para>
The application ID (as above) is the first parameter. The action name follows.
</para>
<para>
Optionally, following the action name can be one parameter, in GVariant format, given as a single
argument. Make sure to use sufficient quoting.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<refsect2>
<title>From the commandline</title>
<para>
Launching an application:
</para>
<programlisting>
gapplication launch org.example.fooview
</programlisting>
<para>
Opening a file with an application:
</para>
<programlisting>
gapplication launch org.example.fooview ~/file.foo
</programlisting>
<para>
Opening many files with an application:
</para>
<programlisting>
gapplication launch org.example.fooview ~/foos/*.foo
</programlisting>
<para>
Invoking an action on an application:
</para>
<programlisting>
gapplication action org.example.fooview create
</programlisting>
<para>
Invoking an action on an application, with an action:
</para>
<programlisting>
gapplication action org.example.fooview show-item '"item_id_828739"'
</programlisting>
</refsect2>
<refsect2>
<title>
From the <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> file
</title>
<para>
The commandline interface of <command>gapplication</command> was designed so that it could be used
directly from the <varname>Exec</varname> line of a <filename class='extension'>.desktop</filename>
file.
</para>
<para>
You might want to do this to allow for backwards compatibility with implementations of the specification
that do not understand how to do D-Bus activation, without having to install a separate utility program.
</para>
<para>
Consider the following example:
</para>
<programlisting>
[Desktop Entry]
Version=1.1
Type=Application
Name=Foo Viewer
DBusActivatable=true
MimeType=image/x-foo;
Exec=gapplication launch org.example.fooview %F
Actions=gallery;create;
[Desktop Action gallery]
Name=Browse Gallery
Exec=gapplication action org.example.fooview gallery
[Desktop Action create]
Name=Create a new Foo!
Exec=gapplication action org.example.fooview create
</programlisting>
</refsect2>
<refsect2>
<title>From a script</title>
<para>
If installing an application that supports D-Bus activation you may still want to put a file in
<filename class='directory'>/usr/bin</filename> so that your program can be started from a terminal.
</para>
<para>
It is possible for this file to be a shell script. The script can handle arguments such as --help and
--version directly. It can also parse other command line arguments and convert them to uses of
<command>gapplication</command> to activate the application, open files, or invoke actions.
</para>
<para>
Here is a simplified example, as may be installed in <filename>/usr/bin/fooview</filename>:
</para>
<programlisting>
#!/bin/sh
case "$1" in
--help)
echo "see 'man fooview' for more information"
;;
--version)
echo "fooview 1.2"
;;
--gallery)
gapplication action org.example.fooview gallery
;;
--create)
gapplication action org.example.fooview create
;;
-*)
echo "unrecognised commandline argument"
exit 1
;;
*)
gapplication launch org.example.fooview "$@"
;;
esac
</programlisting>
</refsect2>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<ulink url='http://standards.freedesktop.org/desktop-entry-spec/latest/'>Desktop Entry Specification</ulink>,
<citerefentry>
<refentrytitle>gdbus</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>xdg-open</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>desktop-file-validate</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
docs/reference/gio/gdbus-codegen.xml
+1054
View File
File diff suppressed because it is too large Load Diff
docs/reference/gio/gdbus.xml
+416
View File
@@ -0,0 +1,416 @@
<refentry id="gdbus" lang="en">
<refentryinfo>
<title>gdbus</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>David</firstname>
<surname>Zeuthen</surname>
<email>zeuthen@gmail.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gdbus</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gdbus</refname>
<refpurpose>Tool for working with D-Bus objects</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">introspect</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<group>
<arg choice="plain">--xml</arg>
</group>
<group>
<arg choice="plain">--recurse</arg>
</group>
<group>
<arg choice="plain">--only-properties</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">monitor</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<group>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">call</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg>
<group>
<arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
</group>
<arg choice="plain">ARG1</arg>
<arg choice="plain" rep="repeat">ARG2</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">emit</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg>
<group>
<arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg>
</group>
<arg choice="plain">ARG1</arg>
<arg choice="plain" rep="repeat">ARG2</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">wait</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--activate <replaceable>bus_name</replaceable></arg>
<group>
<arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
</group>
<arg choice="plain"><replaceable>bus_name</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gdbus</command> is a simple tool for working with D-Bus objects.
</para>
</refsect1>
<refsect1>
<title>Commands</title>
<variablelist>
<varlistentry>
<term><option>introspect</option></term>
<listitem><para>
Prints out interfaces and property values for a remote object.
For this to work, the owner of the object needs to implement the
<literal>org.freedesktop.DBus.Introspectable</literal> interface.
If the <option>--xml</option> option is used, the returned
introspection XML is printed, otherwise a parsed pretty
representation is printed.
The <option>--recurse</option> option can be used to
introspect children (and their children and so on) and the
<option>--only-properties</option> option can be used to
only print the interfaces with properties.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>monitor</option></term>
<listitem><para>
Monitors one or all objects owned by the owner of
<replaceable>bus_name</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>call</option></term>
<listitem><para>
Invokes a method on a remote object. Each argument to pass to the
method must be specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link> except that strings do
not need explicit quotes. The return values are printed out as
serialized <link linkend="GVariant"><type>GVariant</type></link>
values.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>emit</option></term>
<listitem><para>
Emits a signal. Each argument to include in the signal must be specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link> except that strings do
not need explicit quotes.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>wait</option></term>
<listitem><para>
Waits until <replaceable>bus_name</replaceable> is owned by some
process on the bus. If the <option>--activate</option> is specified,
that bus name will be auto-started first. It may be the same as the
bus name being waited for, or different.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exit.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Bash Completion</title>
<para>
<command>gdbus</command> ships with a bash completion script to
complete commands, destinations, bus names, object paths and
interface/method names.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
This shows how to introspect an object - note that the value of each
property is displayed:
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.NetworkManager \
--object-path /org/freedesktop/NetworkManager/Devices/0
node /org/freedesktop/NetworkManager/Devices/0 {
interface org.freedesktop.DBus.Introspectable {
methods:
Introspect(out s data);
};
interface org.freedesktop.DBus.Properties {
methods:
Get(in s interface,
in s propname,
out v value);
Set(in s interface,
in s propname,
in v value);
GetAll(in s interface,
out a{sv} props);
};
interface org.freedesktop.NetworkManager.Device.Wired {
signals:
PropertiesChanged(a{sv} arg_0);
properties:
readonly b Carrier = false;
readonly u Speed = 0;
readonly s HwAddress = '00:1D:72:88:BE:97';
};
interface org.freedesktop.NetworkManager.Device {
methods:
Disconnect();
signals:
StateChanged(u arg_0,
u arg_1,
u arg_2);
properties:
readonly u DeviceType = 1;
readonly b Managed = true;
readwrite o Ip6Config = '/';
readwrite o Dhcp4Config = '/';
readwrite o Ip4Config = '/';
readonly u State = 2;
readwrite u Ip4Address = 0;
readonly u Capabilities = 3;
readonly s Driver = 'e1000e';
readwrite s Interface = 'eth0';
readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
};
};
</programlisting>
<para>
The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process:
</para>
<programlisting>
$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties
node / {
node /org {
node /org/freedesktop {
node /org/freedesktop/UPower {
interface org.freedesktop.UPower {
properties:
readonly b IsDocked = true;
readonly b LidForceSleep = false;
readonly b LidIsPresent = false;
readonly b LidIsClosed = false;
readonly b OnLowBattery = false;
readonly b OnBattery = false;
readonly b CanHibernate = true;
readonly b CanSuspend = true;
readonly s DaemonVersion = '0.9.10';
};
node /org/freedesktop/UPower/Policy {
};
node /org/freedesktop/UPower/Wakeups {
interface org.freedesktop.UPower.Wakeups {
properties:
readonly b HasCapability = true;
};
};
};
};
};
};
</programlisting>
<para>
In a similar fashion, the <option>introspect</option> command can be
used to learn details about the <literal>Notify</literal> method:
</para>
<programlisting>
[...]
interface org.freedesktop.Notifications {
methods:
GetServerInformation(out s return_name,
out s return_vendor,
out s return_version,
out s return_spec_version);
GetCapabilities(out as return_caps);
CloseNotification(in u id);
Notify(in s app_name,
in u id,
in s icon,
in s summary,
in s body,
in as actions,
in a{sv} hints,
in i timeout,
out u return_id);
};
[...]
</programlisting>
<para>
With this information, it's easy to use the <option>call</option>
command to display a notification
</para>
<programlisting>
$ gdbus call --session \
--dest org.freedesktop.Notifications \
--object-path /org/freedesktop/Notifications \
--method org.freedesktop.Notifications.Notify \
my_app_name \
42 \
gtk-dialog-info \
"The Summary" \
"Here's the body of the notification" \
[] \
{} \
5000
(uint32 12,)
</programlisting>
<para>
Monitoring all objects on a service:
</para>
<programlisting>
$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
The name org.freedesktop.ConsoleKit is owned by :1.15
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
</programlisting>
<para>
Monitoring a single object on a service:
</para>
<programlisting>
$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
The name org.freedesktop.NetworkManager is owned by :1.5
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5c&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5e&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
</programlisting>
<para>
Emitting a signal:
</para>
<programlisting>
$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
</programlisting>
<para>
Emitting a signal to a specific process:
</para>
<programlisting>
$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
</programlisting>
<para>
Waiting for a well-known name to be owned on the bus; this will
<emphasis>not</emphasis> auto-start the service:
</para>
<programlisting>
$ gdbus wait --session org.bar.SomeName
</programlisting>
<para>
Auto-starting then waiting for a well-known name to be owned on the bus:
</para>
<programlisting>
$ gdbus wait --session --activate org.bar.SomeName
</programlisting>
<para>
Auto-starting a different service, then waiting for a well-known name to be
owned on the bus. This is useful in situations where
<replaceable>SomeName</replaceable> is not directly activatable:
</para>
<programlisting>
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
</programlisting>
<para>
Waiting for a well-known name and giving up after 30 seconds. By default,
the timeout is disabled; or set <option>--timeout</option> to 0 to disable it:
</para>
<programlisting>
$ gdbus wait --session --timeout 30 org.bar.SomeName
</programlisting>
</refsect1>
<refsect1>
<title>Bugs</title>
<para>
Please send bug reports to either the distribution bug tracker
or the upstream bug tracker at
<ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new"/>.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry>
<refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
docs/reference/gio/gio-docs-unix.xml
+3
View File
@@ -0,0 +1,3 @@
<chapter id='unix-support'>
<!--FIXME: fill this with unix APIs that cannot build on Windows -->
</chapter>
docs/reference/gio/gio-docs-win32.xml
+6
View File
@@ -0,0 +1,6 @@
<chapter id='win32-support'>
<title>Win32 support</title>
<xi:include href="xml/gwin32registrykey.xml"/>
<xi:include href="xml/gwin32inputstream.xml"/>
<xi:include href="xml/gwin32outputstream.xml"/>
</chapter>
docs/reference/gio/gio-docs.xml
+378
View File
@@ -0,0 +1,378 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book lang="en" id="gio" xmlns:xi="http://www.w3.org/2003/XInclude">
<title>GIO Reference Manual</title>
<bookinfo>
<title>GIO Reference Manual</title>
<releaseinfo>
for GIO &version;
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="https://developer.gnome.org/gio/unstable/">https://developer.gnome.org/gio/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<xi:include href="xml/overview.xml"/>
<part>
<title>API Reference</title>
<chapter id="file_ops">
<title>File Operations</title>
<xi:include href="xml/gfile.xml"/>
<xi:include href="xml/gfileattribute.xml"/>
<xi:include href="xml/gfileinfo.xml"/>
<xi:include href="xml/gfileenumerator.xml"/>
<xi:include href="xml/gioerror.xml"/>
<xi:include href="xml/gmountoperation.xml"/>
</chapter>
<chapter id="file_mon">
<title>File System Monitoring</title>
<xi:include href="xml/gfilemonitor.xml"/>
</chapter>
<chapter id="utils">
<title>File-related Utilities</title>
<xi:include href="xml/gfilenamecompleter.xml"/>
</chapter>
<chapter id="async">
<title>Asynchronous I/O</title>
<xi:include href="xml/gcancellable.xml"/>
<xi:include href="xml/gasyncresult.xml"/>
<xi:include href="xml/gtask.xml"/>
<xi:include href="xml/gioscheduler.xml"/>
<xi:include href="xml/gsimpleasyncresult.xml"/>
</chapter>
<chapter id="conversion">
<title>Data conversion</title>
<xi:include href="xml/gconverter.xml"/>
<xi:include href="xml/gcharsetconverter.xml"/>
<xi:include href="xml/gzcompressor.xml"/>
<xi:include href="xml/gzdecompressor.xml"/>
</chapter>
<chapter id="streaming">
<title>Streaming I/O</title>
<xi:include href="xml/gseekable.xml"/>
<xi:include href="xml/ginputstream.xml"/>
<xi:include href="xml/goutputstream.xml"/>
<xi:include href="xml/giostream.xml"/>
<xi:include href="xml/gsimpleiostream.xml"/>
<xi:include href="xml/gfileinputstream.xml"/>
<xi:include href="xml/gfileoutputstream.xml"/>
<xi:include href="xml/gfileiostream.xml"/>
<xi:include href="xml/gfiledescriptorbased.xml"/>
<xi:include href="xml/gfilterinputstream.xml"/>
<xi:include href="xml/gfilteroutputstream.xml"/>
<xi:include href="xml/gmemoryinputstream.xml"/>
<xi:include href="xml/gmemoryoutputstream.xml"/>
<xi:include href="xml/gbufferedinputstream.xml"/>
<xi:include href="xml/gbufferedoutputstream.xml"/>
<xi:include href="xml/gdatainputstream.xml"/>
<xi:include href="xml/gdataoutputstream.xml"/>
<xi:include href="xml/gunixinputstream.xml"/>
<xi:include href="xml/gunixoutputstream.xml"/>
<xi:include href="xml/gconverterinputstream.xml"/>
<xi:include href="xml/gconverteroutputstream.xml"/>
<xi:include href="xml/gpollableinputstream.xml"/>
<xi:include href="xml/gpollableoutputstream.xml"/>
<xi:include href="xml/gpollableutils.xml"/>
</chapter>
<chapter id="types">
<title>File types and applications</title>
<xi:include href="xml/gcontenttype.xml"/>
<xi:include href="xml/gappinfo.xml"/>
<xi:include href="xml/gappinfomonitor.xml"/>
<xi:include href="xml/gdesktopappinfo.xml"/>
</chapter>
<chapter id="volume_mon">
<title>Volumes and Drives</title>
<xi:include href="xml/gvolumemonitor.xml"/>
<xi:include href="xml/gvolume.xml"/>
<xi:include href="xml/gmount.xml"/>
<xi:include href="xml/gdrive.xml"/>
<xi:include href="xml/gunixmounts.xml"/>
</chapter>
<chapter id="icons">
<title>Icons</title>
<xi:include href="xml/gicon.xml"/>
<xi:include href="xml/gfileicon.xml"/>
<xi:include href="xml/gbytesicon.xml"/>
<xi:include href="xml/gloadableicon.xml"/>
<xi:include href="xml/gthemedicon.xml"/>
<xi:include href="xml/gemblemedicon.xml"/>
<xi:include href="xml/gemblem.xml"/>
</chapter>
<chapter id="failable_initialization">
<title>Failable Initialization</title>
<xi:include href="xml/ginitable.xml"/>
<xi:include href="xml/gasyncinitable.xml"/>
</chapter>
<chapter id="subprocesses">
<title>Subprocesses</title>
<xi:include href="xml/gsubprocess.xml"/>
<xi:include href="xml/gsubprocesslauncher.xml"/>
</chapter>
<chapter id="networking">
<title>Low-level network support</title>
<xi:include href="xml/gsocket.xml"/>
<xi:include href="xml/gdatagrambased.xml"/>
<xi:include href="xml/ginetaddress.xml"/>
<xi:include href="xml/ginetaddressmask.xml"/>
<xi:include href="xml/gsocketaddress.xml"/>
<xi:include href="xml/ginetsocketaddress.xml"/>
<xi:include href="xml/gunixsocketaddress.xml"/>
<xi:include href="xml/gnativesocketaddress.xml"/>
<xi:include href="xml/gsocketcontrolmessage.xml"/>
<xi:include href="xml/gunixfdlist.xml"/>
<xi:include href="xml/gunixfdmessage.xml"/>
<xi:include href="xml/gcredentials.xml"/>
<xi:include href="xml/gunixcredentialsmessage.xml"/>
<xi:include href="xml/gproxy.xml"/>
<xi:include href="xml/gproxyaddress.xml"/>
<xi:include href="xml/gnetworking.xml"/>
</chapter>
<chapter id="highlevel-socket">
<title>High-level network functionallity</title>
<xi:include href="xml/gsocketclient.xml"/>
<xi:include href="xml/gsocketconnection.xml"/>
<xi:include href="xml/gunixconnection.xml"/>
<xi:include href="xml/gtcpconnection.xml"/>
<xi:include href="xml/gtcpwrapperconnection.xml"/>
<xi:include href="xml/gsocketlistener.xml"/>
<xi:include href="xml/gsocketservice.xml"/>
<xi:include href="xml/gthreadedsocketservice.xml"/>
<xi:include href="xml/gnetworkmonitor.xml"/>
</chapter>
<chapter id="tls">
<title>TLS (SSL) support</title>
<xi:include href="xml/gtls.xml"/>
<xi:include href="xml/gtlscertificate.xml"/>
<xi:include href="xml/gtlsconnection.xml"/>
<xi:include href="xml/gtlsclientconnection.xml"/>
<xi:include href="xml/gtlsserverconnection.xml"/>
<xi:include href="xml/gdtlsconnection.xml"/>
<xi:include href="xml/gdtlsclientconnection.xml"/>
<xi:include href="xml/gdtlsserverconnection.xml"/>
<xi:include href="xml/gtlsbackend.xml"/>
<xi:include href="xml/gtlsdatabase.xml"/>
<xi:include href="xml/gtlsfiledatabase.xml"/>
<xi:include href="xml/gtlsinteraction.xml"/>
<xi:include href="xml/gtlspassword.xml"/>
</chapter>
<chapter id="resolver">
<title>DNS resolution</title>
<xi:include href="xml/gresolver.xml"/>
<xi:include href="xml/gproxyresolver.xml"/>
<xi:include href="xml/gsimpleproxyresolver.xml"/>
<xi:include href="xml/gsocketconnectable.xml"/>
<xi:include href="xml/gsocketaddressenumerator.xml"/>
<xi:include href="xml/gproxyaddressenumerator.xml"/>
<xi:include href="xml/gnetworkaddress.xml"/>
<xi:include href="xml/gnetworkservice.xml"/>
<xi:include href="xml/gsrvtarget.xml"/>
</chapter>
<chapter id="gdbus-lowlevel">
<title>Low-level D-Bus Support</title>
<xi:include href="xml/gdbusutils.xml"/>
<xi:include href="xml/gdbusaddress.xml"/>
<xi:include href="xml/gdbusintrospection.xml"/>
<xi:include href="xml/gdbuserror.xml"/>
<xi:include href="xml/gdbusmessage.xml"/>
<xi:include href="xml/gdbusconnection.xml"/>
<xi:include href="xml/gdbusmethodinvocation.xml"/>
<xi:include href="xml/gdbusserver.xml"/>
<xi:include href="xml/gdbusauthobserver.xml"/>
</chapter>
<chapter id="gdbus-convenience">
<title>High-level D-Bus Support</title>
<xi:include href="xml/gdbusnameowning.xml"/>
<xi:include href="xml/gdbusnamewatching.xml"/>
<xi:include href="xml/gdbusinterface.xml"/>
<xi:include href="xml/gdbusinterfaceskeleton.xml"/>
<xi:include href="xml/gdbusproxy.xml"/>
<xi:include href="xml/gdbusobject.xml"/>
<xi:include href="xml/gdbusobjectskeleton.xml"/>
<xi:include href="xml/gdbusobjectproxy.xml"/>
<xi:include href="xml/gdbusobjectmanager.xml"/>
<xi:include href="xml/gdbusobjectmanagerserver.xml"/>
<xi:include href="xml/gdbusobjectmanagerclient.xml"/>
</chapter>
<chapter id="settings">
<title>Settings</title>
<xi:include href="xml/gsettings.xml"/>
<xi:include href="xml/gsettingsbackend.xml"/>
<xi:include href="xml/gsettingsschema.xml"/>
</chapter>
<chapter id="resources">
<title>Resources</title>
<xi:include href="xml/gresource.xml"/>
</chapter>
<chapter id='permissions'>
<title>Permissions</title>
<xi:include href="xml/gpermission.xml"/>
<xi:include href="xml/gsimplepermission.xml"/>
</chapter>
<chapter id='data-models'>
<title>Data Models</title>
<xi:include href="xml/glistmodel.xml"/>
<xi:include href="xml/gliststore.xml"/>
</chapter>
<chapter id="application">
<title>Application support</title>
<xi:include href="xml/gapplication.xml"/>
<xi:include href="xml/gapplicationcommandline.xml"/>
<xi:include href="xml/gactiongroup.xml"/>
<xi:include href="xml/gactionmap.xml"/>
<xi:include href="xml/gsimpleactiongroup.xml"/>
<xi:include href="xml/gaction.xml"/>
<xi:include href="xml/gsimpleaction.xml"/>
<xi:include href="xml/gpropertyaction.xml"/>
<xi:include href="xml/gremoteactiongroup.xml"/>
<xi:include href="xml/gactiongroupexporter.xml"/>
<xi:include href="xml/gdbusactiongroup.xml"/>
<xi:include href="xml/gmenumodel.xml"/>
<xi:include href="xml/gmenu.xml"/>
<xi:include href="xml/gmenuexporter.xml"/>
<xi:include href="xml/gdbusmenumodel.xml"/>
<xi:include href="xml/gnotification.xml"/>
</chapter>
<chapter id="extending">
<title>Extending GIO</title>
<xi:include href="xml/gvfs.xml"/>
<xi:include href="xml/giomodule.xml"/>
<xi:include href="xml/extensionpoints.xml"/>
</chapter>
<chapter id="tools">
<title>GIO Tools</title>
<xi:include href="gio-querymodules.xml"/>
<xi:include href="gsettings.xml"/>
<xi:include href="glib-compile-schemas.xml"/>
<xi:include href="glib-compile-resources.xml"/>
<xi:include href="gdbus.xml"/>
<xi:include href="xml/gdbus-codegen.xml"/>
<xi:include href="gresource.xml"/>
<xi:include href="gapplication.xml"/>
<xi:include href="gio.xml"/>
</chapter>
<chapter id="testing">
<title>GIO Testing</title>
<xi:include href="xml/gtestdbus.xml"/>
</chapter>
<xi:include href="gio-docs-platform.xml"/>
</part>
<part id="migrating">
<title>Migrating to GIO</title>
<xi:include href="xml/migrating-posix.xml"/>
<xi:include href="xml/migrating-gnome-vfs.xml"/>
<xi:include href="xml/migrating-gconf.xml"/>
<xi:include href="xml/migrating-gdbus.xml"/>
</part>
<chapter id="gio-hierarchy">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
<index id="api-index-full">
<title id="index-all">Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-deprecated" role="deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-18" role="2.18">
<title>Index of new symbols in 2.18</title>
<xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-20" role="2.20">
<title>Index of new symbols in 2.20</title>
<xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-22" role="2.22">
<title>Index of new symbols in 2.22</title>
<xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-24" role="2.24">
<title>Index of new symbols in 2.24</title>
<xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-26" role="2.26">
<title>Index of new symbols in 2.26</title>
<xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-28" role="2.28">
<title>Index of new symbols in 2.28</title>
<xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-30" role="2.30">
<title>Index of new symbols in 2.30</title>
<xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-32" role="2.32">
<title>Index of new symbols in 2.32</title>
<xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-34" role="2.34">
<title>Index of new symbols in 2.34</title>
<xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-36" role="2.36">
<title>Index of new symbols in 2.36</title>
<xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-38" role="2.38">
<title>Index of new symbols in 2.38</title>
<xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-40" role="2.40">
<title>Index of new symbols in 2.40</title>
<xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-42" role="2.42">
<title>Index of new symbols in 2.42</title>
<xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-44" role="2.44">
<title>Index of new symbols in 2.44</title>
<xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-46" role="2.46">
<title>Index of new symbols in 2.46</title>
<xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-48" role="2.48">
<title>Index of new symbols in 2.48</title>
<xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-50" role="2.50">
<title>Index of new symbols in 2.50</title>
<xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-52" role="2.52">
<title>Index of new symbols in 2.52</title>
<xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-54" role="2.54">
<title>Index of new symbols in 2.54</title>
<xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-56" role="2.56">
<title>Index of new symbols in 2.56</title>
<xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-58" role="2.58">
<title>Index of new symbols in 2.58</title>
<xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-60" role="2.60">
<title>Index of new symbols in 2.60</title>
<xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>
docs/reference/gio/gio-querymodules.xml
+45
View File
@@ -0,0 +1,45 @@
<refentry id="gio-querymodules" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gio-querymodules</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gio-querymodules</refname>
<refpurpose>GIO module cache creation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gio-querymodules</command>
<arg choice="req" rep="repeat">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gio-querymodules</command> creates a
<filename>giomodule.cache</filename> file in the listed directories.
This file lists the implemented extension points for each module
that has been found. It is used by GIO at runtime to avoid opening
all modules just to find out which extension points they are implementing.
</para>
<para>
GIO modules are usually installed in the <filename>gio/modules</filename>
subdirectory of libdir.
</para>
</refsect1>
</refentry>
docs/reference/gio/gio-sections-common.txt
+4661
View File
File diff suppressed because it is too large Load Diff
docs/reference/gio/gio-sections-win32.txt
+112
View File
@@ -0,0 +1,112 @@
<SECTION>
<FILE>gwin32inputstream</FILE>
<TITLE>GWin32InputStream</TITLE>
GWin32InputStream
g_win32_input_stream_new
g_win32_input_stream_set_close_handle
g_win32_input_stream_get_close_handle
g_win32_input_stream_get_handle
<SUBSECTION Standard>
GWin32InputStreamClass
G_WIN32_INPUT_STREAM
G_IS_WIN32_INPUT_STREAM
G_TYPE_WIN32_INPUT_STREAM
G_WIN32_INPUT_STREAM_CLASS
G_IS_WIN32_INPUT_STREAM_CLASS
G_WIN32_INPUT_STREAM_GET_CLASS
<SUBSECTION Private>
g_win32_input_stream_get_type
GWin32InputStreamPrivate
</SECTION>
<SECTION>
<FILE>gwin32outputstream</FILE>
<TITLE>GWin32OutputStream</TITLE>
GWin32OutputStream
g_win32_output_stream_new
g_win32_output_stream_set_close_handle
g_win32_output_stream_get_close_handle
g_win32_output_stream_get_handle
<SUBSECTION Standard>
GWin32OutputStreamClass
G_WIN32_OUTPUT_STREAM
G_IS_WIN32_OUTPUT_STREAM
G_TYPE_WIN32_OUTPUT_STREAM
G_WIN32_OUTPUT_STREAM_CLASS
G_IS_WIN32_OUTPUT_STREAM_CLASS
G_WIN32_OUTPUT_STREAM_GET_CLASS
<SUBSECTION Private>
g_win32_output_stream_get_type
GWin32OutputStreamPrivate
</SECTION>
<SECTION>
<FILE>gwin32registrykey</FILE>
<SUBSECTION>
GWin32RegistrySubkeyIter
g_win32_registry_subkey_iter_copy
g_win32_registry_subkey_iter_free
g_win32_registry_subkey_iter_assign
<SUBSECTION>
GWin32RegistryValueIter
g_win32_registry_value_iter_copy
g_win32_registry_value_iter_free
g_win32_registry_value_iter_assign
<SUBSECTION>
GWin32RegistryKey
g_win32_registry_key_new
g_win32_registry_key_new_w
g_win32_registry_key_get_child
g_win32_registry_key_get_child_w
<SUBSECTION>
g_win32_registry_subkey_iter_init
g_win32_registry_subkey_iter_clear
g_win32_registry_subkey_iter_n_subkeys
g_win32_registry_subkey_iter_next
g_win32_registry_subkey_iter_get_name
g_win32_registry_subkey_iter_get_name_w
<SUBSECTION>
g_win32_registry_value_iter_init
g_win32_registry_value_iter_clear
g_win32_registry_value_iter_n_values
g_win32_registry_value_iter_next
GWin32RegistryValueType
g_win32_registry_value_iter_get_value_type
g_win32_registry_value_iter_get_name
g_win32_registry_value_iter_get_name_w
g_win32_registry_value_iter_get_data
g_win32_registry_value_iter_get_data_w
<SUBSECTION>
g_win32_registry_key_get_value
g_win32_registry_key_get_value_w
g_win32_registry_key_get_path
g_win32_registry_key_get_path_w
GWin32RegistryKeyWatchCallbackFunc
GWin32RegistryKeyWatcherFlags
g_win32_registry_key_watch
g_win32_registry_key_has_changed
g_win32_registry_key_erase_change_indicator
<SUBSECTION Standard>
GWin32RegistryKeyClass
<SUBSECTION Private>
GWin32RegistryKeyPrivate
g_win32_registry_key_get_type
g_win32_registry_subkey_iter_get_type
g_win32_registry_value_iter_get_type
G_TYPE_WIN32_REGISTRY_KEY
G_WIN32_REGISTRY_KEY
G_WIN32_REGISTRY_KEY_CLASS
G_IS_WIN32_REGISTRY_KEY
G_IS_WIN32_REGISTRY_KEY_CLASS
G_WIN32_REGISTRY_KEY_GET_CLASS
G_TYPE_WIN32_REGISTRY_SUBKEY_ITER
G_TYPE_WIN32_REGISTRY_VALUE_ITER
</SECTION>
docs/reference/gio/gio.xml
+738
View File
@@ -0,0 +1,738 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry id="gio">
<refentryinfo>
<title>gio</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
<email>mclasen@redhat.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gio</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gio</refname>
<refpurpose>GIO commandline tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">version</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">cat</arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">copy</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">info</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">list</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mime</arg>
<arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
<arg choice="opt"><replaceable>HANDLER</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mkdir</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">monitor</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mount</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">move</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">open</arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">rename</arg>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>NAME</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">remove</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">save</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">set</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">trash</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">tree</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>gio</command> is a utility that makes many of the GIO
features available from the commandline. In doing so, it provides
commands that are similar to traditional utilities, but let you
use GIO locations instead of local files: for example you can use
something like <filename>smb://server/resource/file.txt</filename>
as a location.</para>
<para>Plain filenames which contain a colon will be interpreted as URIs
with an unknown protocol. To avoid this, prefix them with a path such as
<filename>./</filename>, or with the <literal>file:</literal> protocol.</para>
</refsect1>
<refsect1>
<title>Commands</title>
<variablelist>
<varlistentry>
<term>
<command>help</command>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</term>
<listitem>
<para>Displays a short synopsis of the available commands or provides
detailed help on a specific command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>version</command>
</term>
<listitem>
<para>Prints the GLib version to which <command>gio</command>
belongs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>cat</command>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Concatenates the given files and prints them to the standard
output.</para>
<para>The <command>cat</command> command works just like the traditional <command>cat</command> utility.</para>
<para>Note: just pipe through <command>cat</command> if you need its formatting options
like <option>-n</option>, <option>-T</option> or other.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>copy</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Copies one or more files from <replaceable>SOURCE</replaceable>
to <replaceable>DESTINATION</replaceable>. If more than one source
is specified, the destination must be a directory.</para>
<para>The <command>copy</command> command is similar to the traditional <command>cp</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-T</option>, <option>--no-target-directory</option></term>
<listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--progress</option></term>
<listitem><para>Show progress.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option>, <option>--interactive</option></term>
<listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--preserve</option></term>
<listitem><para>Preserve all attributes of copied files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option>, <option>--backup</option></term>
<listitem><para>Create backups of existing destination files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option>, <option>--no-dereference</option></term>
<listitem><para>Never follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>info</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Shows information about the given locations.</para>
<para>The <command>info</command> command is similar to the traditional <command>ls</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-w</option>, <option>--query-writable</option></term>
<listitem><para>List writable attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--filesystem</option></term>
<listitem><para>Show information about the filesystem that the given
locations reside on.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
<listitem><para>The attributes to get.</para>
<para>Attributes can be specified with their GIO name, e.g.
<literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
which matches all attributes. Several attributes or groups
of attributes can be specified, separated by comma.</para>
<para>By default, all attributes are listed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Lists the contents of the given locations. If no location is
given, the contents of the current directory are shown.</para>
<para>The <command>list</command> command is similar to the traditional <command>ls</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
<listitem><para>The attributes to get.</para>
<para>Attributes can be specified with their GIO name, e.g.
<literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
which matches all attributes. Several attributes or groups
of attributes can be specified, separated by comma.</para>
<para>By default, all attributes are listed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option>, <option>--hidden</option></term>
<listitem><para>Show hidden files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--long</option></term>
<listitem><para>Use a long listing format.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--print-uris</option></term>
<listitem><para>Print full URIs.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mime</command>
<arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
<arg choice="opt"><replaceable>HANDLER</replaceable></arg>
</term>
<listitem>
<para>If no handler is given, the <command>mime</command> command lists the
registered and recommended applications for the mimetype.
If a handler is given, it is set as the default handler for
the mimetype.</para>
<para>Handlers must be specified by their desktop file name,
including the extension. Example: <literal>org.gnome.gedit.desktop</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mkdir</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Creates directories.</para>
<para>The <command>mkdir</command> command is similar to the traditional <command>mkdir</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-p</option>, <option>--parent</option></term>
<listitem><para>Create parent directories when necessary.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>monitor</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Monitors files or directories for changes, such as creation
deletion, content and attribute changes, and mount and unmount
operations affecting the monitored locations.</para>
<para>The <command>monitor</command> command uses the GIO file monitoring APIs to do
its job. GIO has different implementations for different platforms.
The most common implementation on Linux uses inotify.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-d</option>, <option>--dir=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the given location as a directory. Normally,
the file type is used to determine whether to monitor a file or directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--file=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the given location as a file. Normally,
the file type is used to determine whether to monitor a file or directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-D</option>, <option>--direct=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the file directly. This allows changes made via hardlinks to be captured.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--silent=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the file directly, but don’t report changes.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--no-moves</option></term>
<listitem><para>Report moves and renames as simple deleted/created events.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option>, <option>--mounts</option></term>
<listitem><para>Watch for mount events.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mount</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Provides commandline access to various aspects of GIO’s mounting
functionality.</para>
<para>Mounting refers to the traditional concept of arranging multiple
file systems and devices in a single tree, rooted at <filename>/</filename>. Classical
mounting happens in the kernel and is controlled by the mount utility.
GIO expands this concept by introducing mount daemons that can make
file systems available to GIO applications without kernel
involvement.</para>
<para>GIO mounts can require authentication, and the <command>mount</command> command
may ask for user IDs, passwords, and so on, when required.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-m</option>, <option>--mountable</option></term>
<listitem><para>Mount as mountable.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--device=<replaceable>DEVICE</replaceable></option></term>
<listitem><para>Mount volume with device file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--unmount</option></term>
<listitem><para>Unmount the location.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--eject</option></term>
<listitem><para>Eject the location.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--unmount-scheme=<replaceable>SCHEME</replaceable></option></term>
<listitem><para>Unmount all mounts with the given scheme.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore outstanding file operations when unmounting or ejecting.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--anonymous</option></term>
<listitem><para>Use an anonymous user when authenticating.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--list</option></term>
<listitem><para>List all GIO mounts.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option>, <option>--monitor</option></term>
<listitem><para>Monitor mount-related events.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option>, <option>--detail</option></term>
<listitem><para>Show extra information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-pim</option></term>
<listitem><para>The numeric PIM when unlocking a VeraCrypt volume.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-hidden</option></term>
<listitem><para>Mount a TCRYPT hidden volume.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-system</option></term>
<listitem><para>Mount a TCRYPT system volume.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>move</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Moves one or more files from <replaceable>SOURCE</replaceable>
to <replaceable>DESTINATION</replaceable>. If more than one source
is specified, the destination must be a directory.</para>
<para>The <command>move</command> command is similar to the traditional <command>mv</command> utility.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>open</command>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Opens files with the default application that is registered
to handle files of this type.</para>
<para>GIO obtains this information from the shared-mime-info
database, with per-user overrides stored in
<filename><envar>$XDG_DATA_HOME</envar>/applications/mimeapps.list</filename>.</para>
<para>The <command>mime</command> command can be used to change the default handler for
a mimetype.</para>
<para>Environment variables will not be set on the application, as it
may be an existing process which is activated to handle the new file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>rename</command>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>NAME</replaceable></arg>
</term>
<listitem>
<para>Renames a file.</para>
<para>The <command>rename</command> command is similar to the traditional <command>rename</command> utility.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>remove</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Deletes each given file.</para>
<para>This command removes files irreversibly. If you want a reversible
way to remove files, see the <command>trash</command> command.</para>
<para>Note that not all URI schemes that are supported by GIO may
allow deletion of files.</para>
<para>The <command>remove</command> command is similar to the traditional <command>rm</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>save</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Reads from standard input and saves the data to the given
location.</para>
<para>This is similar to just redirecting output to a file using
traditional shell syntax, but the <command>save</command> command allows saving to
location that GIO can write to.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-b</option>, <option>--backup</option></term>
<listitem><para>Back up existing destination files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>, <option>--create</option></term>
<listitem><para>Only create the destination if it doesn’t exist yet.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--append</option></term>
<listitem><para>Append to the end of the file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--private</option></term>
<listitem><para>When creating, restrict access to the current user.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--unlink</option></term>
<listitem><para>When replacing, replace as if the destination did not exist.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--print-etag</option></term>
<listitem><para>Print the new ETag in the end.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--etag=<replaceable>ETAG</replaceable></option></term>
<listitem><para>The ETag of the file that is overwritten.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>set</command>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
</term>
<listitem>
<para>Sets a file attribute on a file.</para>
<para>File attributes can be specified with their GIO name, e.g
<literal>standard::icon</literal>. Note that not all GIO file attributes are writable.
Use the <option>--query-writable</option> option of the <command>info</command> command to list
writable file attributes.</para>
<para>If the <replaceable>TYPE</replaceable> is unset,
<replaceable>VALUE</replaceable> does not have to be specified.
If the <replaceable>TYPE</replaceable> is <literal>stringv</literal>, multiple values can be given.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-t</option>, <option>--type=<replaceable>TYPE</replaceable></option></term>
<listitem><para>Specifies the type of the attribute. Supported
types are <literal>string</literal>, <literal>stringv</literal>,
<literal>bytestring</literal>, <literal>boolean</literal>,
<literal>uint32</literal>, <literal>int32</literal>,
<literal>uint64</literal>, <literal>int64</literal> and <literal>unset</literal>.</para>
<para>If the type is not specified, <literal>string</literal> is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>trash</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Sends files or directories to the ‘Trashcan’. This can be a
different folder depending on where the file is located, and not
all file systems support this concept. In the common case that the
file lives inside a user’s home directory, the trash folder is
<filename><envar>$XDG_DATA_HOME</envar>/Trash</filename>.</para>
<para>Note that moving files to the trash does not free up space on
the file system until the ‘Trashcan’ is emptied. If you are interested
in deleting a file irreversibly, see the <command>remove</command> command.</para>
<para>Inspecting and emptying the ‘Trashcan’ is normally supported by
graphical file managers such as Nautilus, but you can also see the
trash with the command: <command>gio list trash://</command>.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--empty</option></term>
<listitem><para>Empty the trash.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>tree</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Lists the contents of the given locations recursively, in a
tree-like format. If no location is given, it defaults to the current
directory.</para>
<para>The <command>tree</command> command is similar to the traditional <command>tree</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--hidden</option></term>
<listitem><para>Show hidden files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--follow-symlinks</option></term>
<listitem><para>Follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>On success 0 is returned, a non-zero failure code otherwise.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry>
<refentrytitle>cat</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>cp</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>ls</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>mkdir</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>mv</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>rm</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>tree</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>
docs/reference/gio/glib-compile-resources.xml
+241
View File
@@ -0,0 +1,241 @@
<refentry id="glib-compile-resources" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-compile-resources</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-compile-resources</refname>
<refpurpose>GLib resource compiler</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-compile-resources</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="req">FILE</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-compile-resources</command> reads the resource description from
<replaceable>FILE</replaceable> and the files that it references
and creates a binary resource bundle that is suitable for use with the
<link linkend="GResource"><type>GResource</type></link> API.
The resulting bundle is then written out as-is, or as C source for linking into
an application.
</para>
<para>
The XML resource files normally have the filename extension <filename>.gresource.xml</filename>.
For a detailed description of the XML file format, see the
<link linkend="GResource"><type>GResource</type></link> documentation.
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Print program version and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--target=<replaceable>TARGET</replaceable></option></term>
<listitem><para>
Store the compiled resources in the file <replaceable>TARGET</replaceable>.
If not specified a filename based on the <replaceable>FILE</replaceable>
basename is used.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sourcedir=<replaceable>DIRECTORY</replaceable></option></term>
<listitem><para>
The files referenced in <replaceable>FILE</replaceable> are loaded from
this directory. If not specified, the current directory is used.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate</option></term>
<listitem><para>
Write the output file in the format selected for by its filename extension:
<variablelist>
<varlistentry>
<term><literal>.c</literal></term>
<listitem><para>C source</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>.h</literal></term>
<listitem><para>C header</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>.gresource</literal></term>
<listitem><para>resource bundle</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-source</option></term>
<listitem><para>
Instead of a writing the resource bundle in binary form create a C source file
that contains the resource bundle. This can then be compiled into an
application for easy access.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-header</option></term>
<listitem><para>
Generate a header file for use with C code generated by
<option>--generate-source</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-dependencies</option></term>
<listitem><para>
Prints the list of files that the resource bundle references to standard output.
This can be used to track dependencies in the build system. For example, the
following make rule would mark <replaceable>test.gresource</replaceable> as
depending on all the files that <replaceable>test.gresource.xml</replaceable>
includes, so that is is automatically rebuilt if any of them change:
<programlisting>
test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
</programlisting>
Note that this may or may not be portable to non-GNU <command>make</command>.
</para>
<para>
Also see <option>--dependency-file</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--c-name</option></term>
<listitem><para>
Specify the prefix used for the C identifiers in the code generated by
<option>--generate-source</option> and <option>--generate-header</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--manual-register</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> uses automatic
initialization of the resource. This works on most systems by using the
compiler support for constructors. However, some (uncommon) compilers may not
support this, you can then specify <option>--manual-register</option>,
which will generate custom register and unregister functions that your code
can manually call at initialization and uninitialization time.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--internal</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> declares all
initialization functions as <type>extern</type>. So they are exported
unless this is prevented by a link script or other means. Since libraries
usually want to use the functions only internally it can be more useful to
declare them as
<link linkend="G-GNUC-INTERNAL:CAPS"><literal>G_GNUC_INTERNAL</literal></link>
which is what <option>--internal</option> does.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--external-data</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> embeds the
resource data as a string literal. When <option>--external-data</option>
is given, the data is only declared in the generated C file, and the data
has to be linked externally.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dependency-file=<replaceable>FILE</replaceable></option></term>
<listitem><para>
Write dependencies in the same style as gcc -M -MF to the given file.
If <option>FILE</option> is -, the dependencies are written to the standard
output. Unlike <option>--generate-dependencies</option>, this option can be
combined with other <option>--generate</option> options to generate dependencies
as a side-effect of generating sources.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-phony-targets</option></term>
<listitem><para>
When creating a dependency file with <option>--dependency-file</option>
include phony targets in the same style as gcc -MP. This would typically
be used with <literal>make</literal>.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Environment</title>
<variablelist>
<varlistentry>
<term><envar>XMLLINT</envar></term>
<listitem><para>
The full path to the <command>xmllint</command> executable. This is used to
preprocess resources with the <literal>xml-stripblanks</literal> preprocessing
option. If this environment variable is not set, <command>xmllint</command> is
searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><envar>GDK_PIXBUF_PIXDATA</envar></term>
<listitem><para>
The full path to the <command>gdk-pixbuf-pixdata</command> executable. This is
used to preprocess resources with the <literal>to-pixdata</literal> preprocessing
option. If this environment variable is not set, <command>gdk-pixbuf-pixdata</command>
is searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><envar>JSON_GLIB_FORMAT</envar></term>
<listitem><para>
The full path to the <command>json-glib-format</command> executable. This is used
to preprocess resources with the <literal>json-stripblanks</literal> preprocessing
option. If this environment variable is not set, <command>json-glib-format</command>
is searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
docs/reference/gio/glib-compile-schemas.xml
+118
View File
@@ -0,0 +1,118 @@
<refentry id="glib-compile-schemas" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-compile-schemas</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-compile-schemas</refname>
<refpurpose>GSettings schema compiler</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-compile-schemas</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="req">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-compile-schemas</command> compiles all the GSettings XML
schema files in <replaceable>DIRECTORY</replaceable> into a binary file
with the name <filename>gschemas.compiled</filename> that can be used
by <link linkend="GSettings"><type>GSettings</type></link>. The XML schema
files must have the filename extension <filename>.gschema.xml</filename>.
For a detailed description of the XML file format, see the
<link linkend="GSettings"><type>GSettings</type></link> documentation.
</para>
<para>
At runtime, GSettings looks for schemas in the
<filename>glib-2.0/schemas</filename> subdirectories of all directories
specified in the <envar>XDG_DATA_DIRS</envar> environment variable. The
usual location to install schema files is
<filename>/usr/share/glib-2.0/schemas</filename>.
</para>
<para>
In addition to schema files, glib-compile-schemas reads 'vendor override'
files, which are key files that can override default values for keys in
the schemas. The group names in the key files are the schema id, and the
values are written in serialized GVariant form.
Vendor override files must have the filename extension
<filename>.gschema.override</filename>.
</para>
<para>
By convention, vendor override files begin with <filename>nn_</filename>
where <filename>nn</filename> is a number from 00 to 99. Higher
numbered files have higher priority (eg: if the same override is made in
a file numbered 10 and then again in a file numbered 20, the override
from 20 will take precedence).
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Print program version and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--targetdir=<replaceable>TARGET</replaceable></option></term>
<listitem><para>
Store <filename>gschemas.compiled</filename> in the <replaceable>TARGET</replaceable> directory instead of <replaceable>DIRECTORY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--strict</option></term>
<listitem><para>
Abort on any errors in schemas. Without this option, faulty schema files are
simply omitted from the resulting compiled schema.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dry-run</option></term>
<listitem><para>
Don't write <filename>gschemas.compiled</filename>. This option can be used
to check <filename>.gschema.xml</filename> sources for errors.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--allow-any-name</option></term>
<listitem><para>
Do not enforce restrictions on key names. Note that this option is purely
to facility the transition from GConf, and will be removed at some time
in the future.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
docs/reference/gio/gresource.xml
+127
View File
@@ -0,0 +1,127 @@
<refentry id="gresource-tool" lang="en">
<refentryinfo>
<title>gresource</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gresource</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gresource</refname>
<refpurpose>GResource tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">list</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="opt"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">details</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="opt"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">extract</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="plain"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="plain">sections</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gresource</command> offers a simple commandline
interface to <link linkend="GResource"><type>GResource</type></link>.
It lets you list and extract resources that have been compiled
into a resource file or included in an elf file (a binary or a
shared library).
</para>
<para>
The file to operate on is specified by the <replaceable>FILE</replaceable>
argument.
</para>
<para>
If an elf file includes multiple sections with resources, it is
possible to select which one to operate on with the
<arg choice="plain">--section</arg> option. Use the
<arg choice="plain">sections</arg> command to find available sections.
</para>
</refsect1>
<refsect1><title>Commands</title>
<variablelist>
<varlistentry>
<term><option>list</option></term>
<listitem><para>
Lists resources. If <replaceable>SECTION</replaceable> is given, only
list resources in this section. If <replaceable>PATH</replaceable> is
given, only list matching resources.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>details</option></term>
<listitem><para>
Lists resources with details. If <replaceable>SECTION</replaceable>
is given, only list resources in this section. If
<replaceable>PATH</replaceable> is given, only list matching resources.
Details include the section, size and compression of each resource.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>extract</option></term>
<listitem><para>
Extracts the resource named by <replaceable>PATH</replaceable> to stdout.
Note that resources may contain binary data.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>sections</option></term>
<listitem><para>
Lists sections containing resources. This is only interesting if
<replaceable>FILE</replaceable> is an elf file.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exits.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
docs/reference/gio/gsettings.xml
+248
View File
@@ -0,0 +1,248 @@
<refentry id="gsettings-tool" lang="en">
<refentryinfo>
<title>gsettings</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gsettings</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gsettings</refname>
<refpurpose>GSettings configuration tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">get</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">monitor</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="opt"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">writable</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">range</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">describe</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">set</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
<arg choice="plain"><replaceable>VALUE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">reset</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">reset-recursively</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-schemas</arg>
<arg choice="opt">--print-paths</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-relocatable-schemas</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-keys</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-children</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-recursively</arg>
<arg choice="opt"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gsettings</command> offers a simple commandline
interface to <link linkend="GSettings"><type>GSettings</type></link>.
It lets you get, set or monitor an individual key for changes.
</para>
<para>
The <replaceable>SCHEMA</replaceable> and <replaceable>KEY</replaceable>
arguments are required for most commands to specify the schema id and the
name of the key to operate on. The schema id may optionally have a
:<replaceable>PATH</replaceable> suffix. Specifying the path is only needed
if the schema does not have a fixed path.
</para>
<para>
When setting a key, you also need specify a <replaceable>VALUE</replaceable>
The format for the value is that of a serialized
<link linkend="GVariant"><type>GVariant</type></link>,
so e.g. a string
must include explicit quotes: "'foo'". This format is also used when printing
out values.
</para>
<para>
Note that gsettings needs a D-Bus session bus connection to write changes to
the dconf database.
</para>
</refsect1>
<refsect1><title>Commands</title>
<variablelist>
<varlistentry>
<term><option>get</option></term>
<listitem><para>
Gets the value of <replaceable>KEY</replaceable>.
The value is printed out as a serialised
<link linkend="GVariant"><type>GVariant</type></link>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>monitor</option></term>
<listitem><para>
Monitors <replaceable>KEY</replaceable> for changes and prints the changed
values. If no <replaceable>KEY</replaceable> is specified, all keys in the
schema are monitored. Monitoring will continue until the process is terminated.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>writable</option></term>
<listitem><para>
Finds out whether <replaceable>KEY</replaceable> is writable.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>range</option></term>
<listitem><para>
Queries the range of valid values for <replaceable>KEY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>describe</option></term>
<listitem><para>
Queries the description of valid values for <replaceable>KEY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>set</option></term>
<listitem><para>
Sets the value of <replaceable>KEY</replaceable> to
<replaceable>VALUE</replaceable>. The value is specified as a serialised
<link linkend="GVariant"><type>GVariant</type></link>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>reset</option></term>
<listitem><para>
Resets <replaceable>KEY</replaceable> to its default value.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>reset-recursively</option></term>
<listitem><para>
Reset all keys under the given <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-schemas</option></term>
<listitem><para>
Lists the installed, non-relocatable schemas.
See <option>list-relocatable-schemas</option> if you are interested in
relocatable schemas. If <optional><option>--print-paths</option></optional>
is given, the path where each schema is mapped is also printed.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-relocatable-schemas</option></term>
<listitem><para>
Lists the installed, relocatable schemas.
See <option>list-schemas</option> if you are interested in
non-relocatable schemas.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-keys</option></term>
<listitem><para>
Lists the keys in <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-children</option></term>
<listitem><para>
Lists the children of <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-recursively</option></term>
<listitem><para>
Lists keys and values, recursively. If no <replaceable>SCHEMA</replaceable>
is given, list keys in all schemas.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exits.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
docs/reference/gio/gvfs-overview.odg
BIN
View File
Binary file not shown.
docs/reference/gio/gvfs-overview.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

docs/reference/gio/menu-example.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

docs/reference/gio/menu-model.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

docs/reference/gio/meson.build
+225
View File
@@ -0,0 +1,225 @@
if get_option('gtk_doc')
subdir('xml')
ignore_headers = [
'fam',
'fen',
'gdbus-2.0',
'gvdb',
'inotify',
'kqueue',
'libasyncns',
'tests',
'win32',
'xdgmime',
'gappinfoprivate.h',
'gapplicationimpl.h',
'gasynchelper.h',
'gcontenttypeprivate.h',
'gcontextspecificgroup.h',
'gcredentialsprivate.h',
'gdbus-daemon-generated.h',
'gdbusactiongroup-private.h',
'gdbusauth.h',
'gdbusauthmechanismanon.h',
'gdbusauthmechanismexternal.h',
'gdbusauthmechanism.h',
'gdbusauthmechanismsha1.h',
'gdbusdaemon.h',
'gdbusprivate.h',
'gdelayedsettingsbackend.h',
'gdocumentportal.h',
'gdummyfile.h',
'gdummyproxyresolver.h',
'gdummytlsbackend.h',
'gfileattribute-priv.h',
'gfileinfo-priv.h',
'ghttpproxy.h',
'giomodule-priv.h',
'gioprivate.h',
'giowin32-priv.h',
'gio_probes.h',
'gio_trace.h',
'gio-tool.h',
'glocaldirectorymonitor.h',
'glocalfileenumerator.h',
'glocalfile.h',
'glocalfileinfo.h',
'glocalfileinputstream.h',
'glocalfileiostream.h',
'glocalfilemonitor.h',
'glocalfileoutputstream.h',
'glocalvfs.h',
'gmountprivate.h',
'gnativevolumemonitor.h',
'gnetworkingprivate.h',
'gnetworkmonitorbase.h',
'gnetworkmonitornetlink.h',
'gnetworkmonitornm.h',
'gnetworkmonitorportal.h',
'gnotificationbackend.h',
'gnotification-private.h',
'gopenuriportal.h',
'gpollfilemonitor.h',
'gportalsupport.h',
'gproxyresolverportal.h',
'gregistrysettingsbackend.h',
'gresourcefile.h',
'gsettingsbackendinternal.h',
'gsettings-mapping.h',
'gsettingsschema-internal.h',
'gsocketinputstream.h',
'gsocketoutputstream.h',
'gsocks4aproxy.h',
'gsocks4proxy.h',
'gsocks5proxy.h',
'gsubprocesslauncher-private.h',
'gthreadedresolver.h',
'gtrashportal.h',
'gunionvolumemonitor.h',
'gunixmount.h',
'gunixresolver.h',
'gunixvolume.h',
'gunixvolumemonitor.h',
'gwin32networkmonitor.h',
'gwin32appinfo.h',
'gwin32mount.h',
'gwin32resolver.h',
'gwin32volumemonitor.h',
'thumbnail-verify.h',
'xdp-dbus.h',
]
sections_files = files('gio-sections-common.txt')
if host_system == 'windows'
ignore_headers += [
'gfiledescriptorbased.h',
'gunixconnection.h',
'gunixcredentialsmessage.h',
'gunixmounts.h',
'gunixfdlist.h',
'gunixfdmessage.h',
'gunixinputstream.h',
'gunixoutputstream.h',
'gunixsocketaddress.h',
'gdesktopappinfo.h',
'gosxappinfo.h',
]
sections_files += files('gio-sections-win32.txt')
platform_file = files('gio-docs-win32.xml')
else
if glib_have_cocoa
ignore_headers += ['gdesktopappinfo.h']
else
ignore_headers += ['gosxappinfo.h']
endif
ignore_headers += [
'gwin32inputstream.h',
'gwin32outputstream.h',
'gwin32registrykey.h',
]
platform_file = files('gio-docs-unix.xml')
endif
ignore_sources = [
'kqueue',
'tests',
'gdbus-daemon-generated.c',
'xdp-dbus.c',
]
# FIXME: ExampleAnimal docs aren't built
docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
version_conf = configuration_data()
version_conf.set('VERSION', meson.project_version())
configure_file(
input: 'version.xml.in',
output: 'version.xml',
configuration: version_conf
)
# FIXME: configure_file() does not support more than one file in input
# argument. If input argument is omitted then meson checks that all items in
# the command array are strings. But if we have an input then extra files
# can be passed in command array.
# See https://github.com/mesonbuild/meson/issues/5893
concat_files_helper = find_program('concat-files-helper.py')
configure_file(
output : 'gio-sections.txt',
input : sections_files[0],
command : [concat_files_helper, '@OUTPUT@'] + sections_files,
)
configure_file(
output : 'gio-docs-platform.xml',
input : platform_file,
copy : true,
)
gnome.gtkdoc('gio',
main_xml : 'gio-docs.xml',
namespace : 'g',
mode : 'none',
dependencies : [libgio_dep, libgobject_dep, libglib_dep],
src_dir : 'gio',
scan_args : gtkdoc_common_scan_args + [
'--rebuild-types',
'--ignore-headers=' + ' '.join(ignore_headers),
],
mkdb_args : [
'--ignore-files=' + ' '.join(ignore_sources),
],
content_files : [
'overview.xml',
'migrating-posix.xml',
'migrating-gnome-vfs.xml',
'migrating-gconf.xml',
'migrating-gdbus.xml',
'gio-querymodules.xml',
'glib-compile-schemas.xml',
'glib-compile-resources.xml',
'gapplication.xml',
'gsettings.xml',
'gresource.xml',
'gdbus.xml',
'gdbus-codegen.xml',
],
expand_content_files : [
'overview.xml',
'migrating-posix.xml',
'migrating-gnome-vfs.xml',
'migrating-gconf.xml',
'migrating-gdbus.xml',
'gdbus-codegen.xml',
],
html_assets : [
'gvfs-overview.png',
'menu-example.png',
'menu-model.png',
],
fixxref_args: [
'--html-dir=' + docpath,
'--extra-dir=' + join_paths('gio', '..', 'glib', 'html'),
'--extra-dir=' + join_paths('gio', '..', 'gobject', 'html'),
],
install: true
)
endif
if get_option('man')
manpages = ['gapplication', 'gio-querymodules', 'glib-compile-schemas',
'glib-compile-resources', 'gsettings', 'gresource', 'gdbus',
'gio', 'gdbus-codegen']
foreach page : manpages
custom_target(page + '-man',
input: page + '.xml',
output: page + '.1',
command: xsltproc_command,
install: true,
install_dir: man1_dir)
endforeach
endif
docs/reference/gio/migrating-gconf.xml
+515
View File
@@ -0,0 +1,515 @@
<chapter>
<title>Migrating from GConf to GSettings</title>
<section>
<title>Before you start</title>
<para>
Converting individual applications and their settings from GConf to
GSettings can be done at will. But desktop-wide settings like font or
theme settings often have consumers in multiple modules. Therefore,
some consideration has to go into making sure that all users of a setting
are converted to GSettings at the same time or that the program
responsible for configuring that setting continues to update the value in
both places.
</para>
<para>
It is always a good idea to have a look at how others have handled
similar problems before.
</para>
</section>
<section>
<title>Conceptual differences</title>
<para>
Conceptually, GConf and GSettings are fairly similar. Both
have a concept of pluggable backends. Both keep information
about keys and their types in schemas. Both have a concept of
mandatory values, which lets you implement lock-down.
</para>
<para>
There are some differences in the approach to schemas. GConf
installs the schemas into the database and has API to handle
schema information (gconf_client_get_default_from_schema(),
gconf_value_get_schema(), etc). GSettings on the other hand
assumes that an application knows its own schemas, and does
not provide API to handle schema information at runtime.
GSettings is also more strict about requiring a schema whenever
you want to read or write a key. To deal with more free-form
information that would appear in schema-less entries in GConf,
GSettings allows for schemas to be 'relocatable'.
</para>
<para>
One difference in the way applications interact with their
settings is that with GConf you interact with a tree of
settings (ie the keys you pass to functions when reading
or writing values are actually paths with the actual name
of the key as the last element. With GSettings, you create
a GSettings object which has an implicit prefix that determines
where the settings get stored in the global tree of settings,
but the keys you pass when reading or writing values are just
the key names, not the full path.
</para>
</section>
<section>
<title>GConfClient (and GConfBridge) API conversion</title>
<para>
Most people use GConf via the high-level #GConfClient API.
The corresponding API is the #GSettings object. While not
every GConfClient function has a direct GSettings equivalent,
many do:
<table id="gconf-client-vs-gsettings">
<tgroup cols="2">
<thead>
<row><entry>GConfClient</entry><entry>GSettings</entry></row>
</thead>
<tbody>
<row><entry>gconf_client_get_default()</entry><entry>no direct equivalent,
instead you call g_settings_new() for the schemas you use</entry></row>
<row><entry>gconf_client_set()</entry><entry>g_settings_set()</entry></row>
<row><entry>gconf_client_get()</entry><entry>g_settings_get()</entry></row>
<row><entry>gconf_client_get_bool()</entry><entry>g_settings_get_boolean()</entry></row>
<row><entry>gconf_client_set_bool()</entry><entry>g_settings_set_boolean()</entry></row>
<row><entry>gconf_client_get_int()</entry><entry>g_settings_get_int()</entry></row>
<row><entry>gconf_client_set_int()</entry><entry>g_settings_set_int()</entry></row>
<row><entry>gconf_client_get_float()</entry><entry>g_settings_get_double()</entry></row>
<row><entry>gconf_client_set_float()</entry><entry>g_settings_set_double()</entry></row>
<row><entry>gconf_client_get_string()</entry><entry>g_settings_get_string()</entry></row>
<row><entry>gconf_client_set_string()</entry><entry>g_settings_set_string()</entry></row>
<row><entry>gconf_client_get_list()</entry><entry>for string lists, see g_settings_get_strv(), else see g_settings_get_value() and #GVariant API</entry></row>
<row><entry>gconf_client_set_list()</entry><entry>for string lists, see g_settings_set_strv(), else see g_settings_set_value() and #GVariant API</entry></row>
<row><entry>gconf_entry_get_is_writable()</entry><entry>g_settings_is_writable()</entry></row>
<row><entry>gconf_client_notify_add()</entry><entry>not required, the #GSettings::changed signal is emitted automatically</entry></row>
<row><entry>gconf_client_add_dir()</entry><entry>not required, each GSettings instance automatically watches all keys in its path</entry></row>
<row><entry>#GConfChangeSet</entry><entry>g_settings_delay(), g_settings_apply()</entry></row>
<row><entry>gconf_client_get_default_from_schema()</entry><entry>no equivalent, applications are expected to know their schema</entry></row>
<row><entry>gconf_client_all_entries()</entry><entry>no equivalent, applications are expected to know their schema, and GSettings does not allow schema-less entries</entry></row>
<row><entry>gconf_client_get_without_default()</entry><entry>no equivalent</entry></row>
<row><entry>gconf_bridge_bind_property()</entry><entry>g_settings_bind()</entry></row>
<row><entry>gconf_bridge_bind_property_full()</entry><entry>g_settings_bind_with_mapping()</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
GConfBridge was a third-party library that used GConf to bind an object property
to a particular configuration key. GSettings offers this service itself.
</para>
<para>
There is a pattern that is sometimes used for GConf, where a setting can have
explicit 'value A', explicit 'value B' or 'use the system default'. With GConf,
'use the system default' is sometimes implemented by unsetting the user value.
</para>
<para>
This is not possible in GSettings, since it does not have API to determine if a value
is the default and does not let you unset values. The recommended way (and much
clearer) way in which this can be implemented in GSettings is to have a separate
'use-system-default' boolean setting.
</para>
</section>
<section>
<title>Change notification</title>
<para>
GConf requires you to call gconf_client_add_dir() and
gconf_client_notify_add() to get change notification. With
GSettings, this is not necessary; signals get emitted automatically
for every change.
</para>
<para>
The #GSettings::changed signal is emitted for each changed key.
There is also a #GSettings::change-event signal that you can handle
if you need to see groups of keys that get changed at the same time.
</para>
<para>
GSettings also notifies you about changes in writability of keys,
with the #GSettings::writable-changed signal (and the
#GSettings::writable-change-event signal).
</para>
</section>
<section><title>Change sets</title>
<para>
GConf has a concept of a set of changes which can be applied or reverted
at once: #GConfChangeSet (GConf doesn't actually apply changes atomically,
which is one of its shortcomings).
</para>
<para>
Instead of a separate object to represent a change set, GSettings has a
'delayed-apply' mode, which can be turned on for a GSettings object by
calling g_settings_delay(). In this mode, changes done to the GSettings
object are not applied - they are still visible when calling g_settings_get()
<emphasis>on the same object</emphasis>, but not to other GSettings instances
or even other processes.
</para>
<para>
To apply the pending changes all at once (GSettings <emphasis>does</emphasis>
atomicity here), call g_settings_apply(). To revert the pending changes,
call g_settings_revert() or just drop the reference to the #GSettings object.
</para>
</section>
<section>
<title>Schema conversion</title>
<para>
If you are porting your application from GConf, most likely you already
have a GConf schema. GConf comes with a commandline tool
gsettings-schema-convert that can help with the task of converting
a GConf schema into an equivalent GSettings schema. The tool is not
perfect and may need assistence in some cases.
</para>
<example><title>An example for using gsettings-schema-convert</title>
<para>Running <userinput>gsettings-schema-convert --gconf --xml --schema-id "org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml destop_gnome_font_rendering.schemas</userinput> on the following <filename>desktop_gnome_font_rendering.schemas</filename> file:
<programlisting>
<![CDATA[
<?xml version="1.0"?>
<gconfschemafile>
<schemalist>
<schema>
<key>/schemas/desktop/gnome/font_rendering/dpi</key>
<applyto>/desktop/gnome/font_rendering/dpi</applyto>
<owner>gnome</owner>
<type>int</type>
<default>96</default>
<locale name="C">
<short>DPI</short>
<long>The resolution used for converting font sizes to pixel sizes, in dots per inch.</long>
</locale>
</schema>
</schemalist>
</gconfschemafile>
]]>
</programlisting>
produces a <filename>org.gnome.font-rendering.gschema.xml</filename> file with the following content:
<programlisting>
<![CDATA[
<schemalist>
<schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/">
<key name="dpi" type="i">
<default>96</default>
<summary>DPI</summary>
<description>The resolution used for converting font sizes to pixel sizes, in dots per inch.</description>
</key>
</schema>
</schemalist>
]]>
</programlisting>
</para>
</example>
<para>
GSettings schemas are identified at runtime by their id (as specified
in the XML source file). It is recommended to use a dotted name as schema
id, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager".
In cases where the settings are general and not specific to one application,
the id should not use StudlyCaps, e.g. "org.gnome.font-rendering".
The filename used for the XML schema source is immaterial, but
schema compiler expects the files to have the extension
<filename>.gschema.xml</filename>. It is recommended to simply
use the schema id as the filename, followed by this extension,
e.g. <filename>org.gnome.SessionManager.gschema.xml</filename>.
</para>
<para>
The XML source file for your GSettings schema needs to get installed
into <filename>$datadir/glib-2.0/schemas</filename>, and needs to be
compiled into a binary form. At runtime, GSettings looks for compiled
schemas in the <filename>glib-2.0/schemas</filename> subdirectories
of all <envar>XDG_DATA_DIRS</envar> directories, so if you install
your schema in a different location, you need to set the
<envar>XDG_DATA_DIRS</envar> environment variable appropriately.
</para>
<para>
Schemas are compiled into binary form by the
<link linkend="glib-compile-schemas">glib-compile-schemas</link> utility.
GIO provides a <literal>glib_compile_schemas</literal>
variable for the schema compiler.
</para>
<para>
You can ignore all of this by using the provided m4 macros. To
do this, add to your <filename>configure.ac</filename>:
<programlisting>
GLIB_GSETTINGS
</programlisting>
The corresponding <filename>Makefile.am</filename> fragment looks like
this:
<programlisting>
# gsettings_SCHEMAS is a list of all the schemas you want to install
gsettings_SCHEMAS = my.app.gschema.xml
# include the appropriate makefile rules for schema handling
@GSETTINGS_RULES@
</programlisting>
</para>
<para>
This is not sufficient on its own. You need to mention what the source
of the <filename>my.app.gschema.xml</filename> file is. If the schema
file is distributed directly with your project's tarball then a mention
in <varname>EXTRA_DIST</varname> is appropriate. If the schema file is
generated from another source then you will need the appropriate rule
for that, plus probably an item in <varname>EXTRA_DIST</varname> for the
source files used by that rule.
</para>
<para>
One possible pitfall in doing schema conversion is that the default
values in GSettings schemas are parsed by the #GVariant parser.
This means that strings need to include quotes in the XML. Also note
that the types are now specified as #GVariant type strings.
<programlisting>
<![CDATA[
<type>string</type>
<default>rgb</default>
]]>
</programlisting>
becomes
<programlisting>
<![CDATA[
<key name="rgba-order" type="s">
<default>'rgb'</default> <!-- note quotes -->
</key>
]]>
</programlisting>
</para>
<para>
Another possible complication is that GConf specifies full paths
for each key, while a GSettings schema has a 'path' attribute that
contains the prefix for all the keys in the schema, and individual
keys just have a simple name. So
<programlisting>
<![CDATA[
<key>/schemas/desktop/gnome/font_rendering/antialiasing</key>
]]>
</programlisting>
becomes
<programlisting>
<![CDATA[
<schema id="org.gnome.font" path="/desktop/gnome/font_rendering/">
<key name="antialiasing" type="s">
]]>
</programlisting>
</para>
<para>
Default values can be localized in both GConf and GSettings schemas,
but GSettings uses gettext for the localization. You can specify
the gettext domain to use in the <tag class="attribute">gettext-domain</tag>
attribute. Therefore, when converting localized defaults in GConf,
<programlisting>
<![CDATA[
<key>/schemas/apps/my_app/font_size</key>
<locale name="C">
<default>18</default>
</locale>
<locale name="be">
<default>24</default>
</locale>
</key>
]]>
</programlisting>
becomes
<programlisting>
<![CDATA[
<schema id="..." gettext-domain="your-domain">
...
<key name="font-size" type="i">
<default l10n="messages" context="font_size">18</default>
</key>
]]>
</programlisting>
</para>
<para>
GSettings uses gettext for translation of default values.
The string that is translated is exactly the string that appears
inside of the <tag class='starttag'>default</tag> element. This
includes the quotation marks that appear around strings.
Default values must be marked with the <varname>l10n</varname>
attribute in the <tag class='starttag'>default</tag> tag, which
should be set as equal to <literal>'messages'</literal> or
<literal>'time'</literal> depending on the desired category. An
optional translation context can also be specified with the
<varname>context</varname> attribute, as in the example. This
is usually recommended, since the string "<literal>18</literal>"
is not particularly easy to translate without context. The
translated version of the default value should be stored in the
specified <varname>gettext-domain</varname>. Care must be taken
during translation to ensure that all translated values remain
syntactically valid; mistakes here will cause runtime errors.
</para>
<para>
GSettings schemas have optional <tag class="starttag">summary</tag> and
<tag class="starttag">description</tag> elements for each key which
correspond to the <tag class="starttag">short</tag> and
<tag class="starttag">long</tag> elements in the GConf schema and
will be used in similar ways by a future gsettings-editor, so you
should use the same conventions for them: The summary is just a short
label with no punctuation, the description can be one or more complete
sentences. If multiple paragraphs are desired for the description, the
paragraphs should be separated by a completely empty line.
</para>
<para>
Translations for these strings will also be handled
via gettext, so you should arrange for these strings to be
extracted into your gettext catalog. One way to do that is to use
intltool. Since intltool 0.50.1, schema files are
supported, so all you have to do is to add your .gschema.xml
files to <filename>POTFILES.in</filename> with a line like
<programlisting>
[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
</programlisting>
</para>
<para>
GSettings is a bit more restrictive about key names than GConf. Key
names in GSettings can be at most 32 characters long, and must only
consist of lowercase characters, numbers and dashes, with no
consecutive dashes. The first character must not be a number or dash,
and the last character cannot be '-'.
</para>
<para>
If you are using the GConf backend for GSettings during the
transition, you may want to keep your key names the same they
were in GConf, so that existing settings in the users GConf
database are preserved. You can achieve this by using the
<option>--allow-any-name</option> with the
<link linkend="glib-compile-schemas">glib-compile-schemas</link> schema
compiler. Note that this option is only meant
to ease the process of porting your application, allowing parts
of your application to continue to access GConf and parts to use
GSettings. By the time you have finished porting your application
you must ensure that all key names are valid.
</para>
</section>
<section><title>Data conversion</title>
<para>
GConf comes with a GSettings backend that can be used to
facility the transition to the GSettings API until you are
ready to make the jump to a different backend (most likely
dconf). To use it, you need to set the <envar>GSETTINGS_BACKEND</envar>
to 'gconf', e.g. by using
<programlisting>
g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE);
</programlisting>
early on in your program. Note that this backend is meant purely
as a transition tool, and should not be used in production.
</para>
<para>
GConf also comes with a utility called
<command>gsettings-data-convert</command>, which is designed to help
with the task of migrating user settings from GConf into another
GSettings backend. It can be run manually, but it is designed to be
executed automatically, every time a user logs in. It keeps track of
the data migrations that it has already done, and it is harmless to
run it more than once.
</para>
<para>
To make use of this utility, you must install a keyfile in the
directory <filename>/usr/share/GConf/gsettings</filename> which
lists the GSettings keys and GConf paths to map to each other, for
each schema that you want to migrate user data for.
</para>
<para>
Here is an example:
<programlisting>
<![CDATA[
[org.gnome.fonts]
antialiasing = /desktop/gnome/font_rendering/antialiasing
dpi = /desktop/gnome/font_rendering/dpi
hinting = /desktop/gnome/font_rendering/hinting
rgba-order = /desktop/gnome/font_rendering/rgba_order
[apps.myapp:/path/to/myapps/]
some-odd-key1 = /apps/myapp/some_ODD-key1
]]>
</programlisting>
The last key demonstrates that it may be necessary to modify the key
name to comply with stricter GSettings key name rules. Of course,
that means your application must use the new key names when looking
up settings in GSettings.
</para>
<para>
The last group in the example also shows how to handle the case
of 'relocatable' schemas, which don't have a fixed path. You can
specify the path to use in the group name, separated by a colon.
</para>
<para>
There are some limitations: <command>gsettings-data-convert</command>
does not do any transformation of the values. And it does not handle
complex GConf types other than lists of strings or integers.
</para>
<para>
Don't forget to require GConf 2.31.1 or newer in your configure
script if you are making use of the GConf backend or the conversion
utility.
</para>
<para>
If, as an application developer, you are interested in manually
ensuring that <command>gsettings-data-convert</command> has been
invoked (for example, to deal with the case where the user is
logged in during a distribution upgrade or for non-XDG desktop
environments which do not run the command as an autostart) you
may invoke it manually during your program initialisation. This
is not recommended for all application authors -- it is your
choice if this use case concerns you enough.
</para>
<para>
Internally, <command>gsettings-data-convert</command> uses a
keyfile to track which settings have been migrated. The
following code fragment will check that keyfile to see if your
data conversion script has been run yet and, if not, will
attempt to invoke the tool to run it. You should adapt it to
your application as you see fit.
</para>
<para>
<programlisting>
<![CDATA[
static void
ensure_migrated (const gchar *name)
{
gboolean needed = TRUE;
GKeyFile *kf;
gchar **list;
gsize i, n;
kf = g_key_file_new ();
g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
NULL, G_KEY_FILE_NONE, NULL);
list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
if (list)
{
for (i = 0; i < n; i++)
if (strcmp (list[i], name) == 0)
{
needed = FALSE;
break;
}
g_strfreev (list);
}
g_key_file_free (kf);
if (needed)
g_spawn_command_line_sync ("gsettings-data-convert",
NULL, NULL, NULL, NULL);
}
]]>
</programlisting>
</para>
<para>
Although there is the possibility that the
<command>gsettings-data-convert</command> script will end up
running multiple times concurrently with this approach, it is
believed that this is safe.
</para>
</section>
</chapter>
docs/reference/gio/migrating-gdbus.xml
+284
View File
@@ -0,0 +1,284 @@
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<chapter>
<title>Migrating to GDBus</title>
<section>
<title>Conceptual differences</title>
<para>
The central concepts of D-Bus are modelled in a very similar way
in dbus-glib and GDBus. Both have objects representing connections,
proxies and method invocations. But there are some important
differences:
<itemizedlist>
<listitem><para>
dbus-glib uses the <ulink
url="http://www.freedesktop.org/wiki/Software/dbus#ReferenceImplementation.28dbus-daemonandlibdbus.29">libdbus
reference implementation</ulink>, GDBus doesn't. Instead, it
relies on GIO streams as transport layer, and has its own
implementation for the D-Bus connection setup and
authentication. Apart from using streams as transport,
avoiding libdbus also lets GDBus avoid some thorny
multithreading issues.
</para></listitem>
<listitem><para>
dbus-glib uses the GObject type system for method arguments and
return values, including a homegrown container specialization
mechanism. GDBus relies on the #GVariant type system which is
explicitly designed to match D-Bus types.
</para></listitem>
<listitem><para>
dbus-glib models only D-Bus interfaces and does not provide
any types for objects. GDBus models both D-Bus interfaces
(via the #GDBusInterface, #GDBusProxy and
#GDBusInterfaceSkeleton types) and objects (via the
#GDBusObject, #GDBusObjectSkeleton and #GDBusObjectProxy types).
</para></listitem>
<listitem><para>
GDBus includes native support for the <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> (via the #GDBusProxy type) and <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> D-Bus interfaces, dbus-glib doesn't.
</para></listitem>
<listitem><para>
The typical way to export an object in dbus-glib involves
generating glue code from XML introspection data using
<command>dbus-binding-tool</command>. GDBus provides a
similar tool called <command><link
linkend="gdbus-codegen">gdbus-codegen</link></command> that
can also generate Docbook D-Bus interface documentation.
</para></listitem>
<listitem><para>
dbus-glib doesn't provide any convenience API for owning and
watching bus names, GDBus provides the g_bus_own_name() and
g_bus_watch_name() family of convenience functions.
</para></listitem>
<listitem><para>
GDBus provides API to parse, generate and work with <link
linkend="gio-D-Bus-Introspection-Data">Introspection
XML</link>, dbus-glib doesn't.
</para></listitem>
<listitem><para>
GTestDBus provides API to create isolated unit tests <link
linkend="gio-D-Bus-Test-Scaffolding">GDBus Test Scaffolding</link>.
</para></listitem>
</itemizedlist>
</para>
</section>
<section>
<title>API comparison</title>
<table id="dbus-glib-vs-gdbus">
<title>dbus-glib APIs and their GDBus counterparts</title>
<tgroup cols="2">
<thead>
<row><entry>dbus-glib</entry><entry>GDBus</entry></row>
</thead>
<tbody>
<row><entry>#DBusGConnection</entry><entry>#GDBusConnection</entry></row>
<row><entry>#DBusGProxy</entry><entry>#GDBusProxy, #GDBusInterface - also see #GDBusObjectProxy</entry></row>
<row><entry>#DBusGObject</entry><entry>#GDBusInterfaceSkeleton, #GDBusInterface - also see #GDBusObjectSkeleton</entry></row>
<row><entry>#DBusGMethodInvocation</entry><entry>#GDBusMethodInvocation</entry></row>
<row><entry>dbus_g_bus_get()</entry><entry>g_bus_get_sync(), also see
g_bus_get()</entry></row>
<row><entry>dbus_g_proxy_new_for_name()</entry><entry>g_dbus_proxy_new_sync() and
g_dbus_proxy_new_for_bus_sync(), also see g_dbus_proxy_new()</entry></row>
<row><entry>dbus_g_proxy_add_signal()</entry><entry>not needed, use the generic #GDBusProxy::g-signal</entry></row>
<row><entry>dbus_g_proxy_connect_signal()</entry><entry>use g_signal_connect() with #GDBusProxy::g-signal</entry></row>
<row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object() - also see g_dbus_object_manager_server_export()</entry></row>
<row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object() - also see g_dbus_object_manager_server_unexport()</entry></row>
<row><entry>dbus_g_object_type_install_info()</entry><entry>introspection data is installed while registering
an object, see g_dbus_connection_register_object()</entry></row>
<row><entry>dbus_g_proxy_begin_call()</entry><entry>g_dbus_proxy_call()</entry></row>
<row><entry>dbus_g_proxy_end_call()</entry><entry>g_dbus_proxy_call_finish()</entry></row>
<row><entry>dbus_g_proxy_call()</entry><entry>g_dbus_proxy_call_sync()</entry></row>
<row><entry>dbus_g_error_domain_register()</entry><entry>g_dbus_error_register_error_domain()</entry></row>
<row><entry>dbus_g_error_has_name()</entry><entry>no direct equivalent, see g_dbus_error_get_remote_error()</entry></row>
<row><entry>dbus_g_method_return()</entry><entry>g_dbus_method_invocation_return_value()</entry></row>
<row><entry>dbus_g_method_return_error()</entry><entry>g_dbus_method_invocation_return_error() and variants</entry></row>
<row><entry>dbus_g_method_get_sender()</entry><entry>g_dbus_method_invocation_get_sender()</entry></row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Owning bus names</title>
<para>
Using dbus-glib, you typically call RequestName manually
to own a name, like in the following excerpt:
<informalexample><programlisting><![CDATA[
error = NULL;
res = dbus_g_proxy_call (system_bus_proxy,
"RequestName",
&error,
G_TYPE_STRING, NAME_TO_CLAIM,
G_TYPE_UINT, DBUS_NAME_FLAG_ALLOW_REPLACEMENT,
G_TYPE_INVALID,
G_TYPE_UINT, &result,
G_TYPE_INVALID);
if (!res)
{
if (error != NULL)
{
g_warning ("Failed to acquire %s: %s",
NAME_TO_CLAIM, error->message);
g_error_free (error);
}
else
{
g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
}
goto out;
}
if (result != DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
{
if (error != NULL)
{
g_warning ("Failed to acquire %s: %s",
NAME_TO_CLAIM, error->message);
g_error_free (error);
}
else
{
g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
}
exit (1);
}
dbus_g_proxy_add_signal (system_bus_proxy, "NameLost",
G_TYPE_STRING, G_TYPE_INVALID);
dbus_g_proxy_connect_signal (system_bus_proxy, "NameLost",
G_CALLBACK (on_name_lost), NULL, NULL);
/* further setup ... */
]]>
</programlisting></informalexample>
</para>
<para>
While you can do things this way with GDBus too, using
g_dbus_proxy_call_sync(), it is much nicer to use the high-level API
for this:
<informalexample><programlisting><![CDATA[
static void
on_name_acquired (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
/* further setup ... */
}
/* ... */
owner_id = g_bus_own_name (G_BUS_TYPE_SYSTEM,
NAME_TO_CLAIM,
G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT,
on_bus_acquired,
on_name_acquired,
on_name_lost,
NULL,
NULL);
g_main_loop_run (loop);
g_bus_unown_name (owner_id);
]]>
</programlisting></informalexample>
Note that g_bus_own_name() works asynchronously and requires
you to enter your mainloop to await the on_name_aquired()
callback. Also note that in order to avoid race conditions (e.g.
when your service is activated by a method call), you have to export
your manager object <emphasis>before</emphasis> acquiring the
name. The on_bus_acquired() callback is the right place to do
such preparations.
</para>
</section>
<section>
<title>Creating proxies for well-known names</title>
<para>
dbus-glib lets you create proxy objects for well-known names, like the
following example:
<informalexample><programlisting><![CDATA[
proxy = dbus_g_proxy_new_for_name (system_bus_connection,
"org.freedesktop.Accounts",
"/org/freedesktop/Accounts",
"org.freedesktop.Accounts");
]]>
</programlisting></informalexample>
For a #DBusGProxy constructed like this, method calls will be sent to
the current owner of the name, and that owner can change over time.
</para>
<para>
The same can be achieved with #GDBusProxy:
<informalexample><programlisting><![CDATA[
error = NULL;
proxy = g_dbus_proxy_new_for_bus_sync (G_BUS_TYPE_SYSTEM,
G_DBUS_PROXY_FLAGS_NONE,
NULL, /* GDBusInterfaceInfo */
"org.freedesktop.Accounts",
"/org/freedesktop/Accounts",
"org.freedesktop.Accounts",
NULL, /* GCancellable */
&error);
]]>
</programlisting></informalexample>
For an added layer of safety, you can specify what D-Bus
interface the proxy is expected to conform to by using the
#GDBusInterfaceInfo type. Additionally, #GDBusProxy loads,
caches and tracks changes to the D-Bus properties on the remote
object. It also sets up match rules so D-Bus signals from the
remote object are delivered locally.
</para>
<para>
The #GDBusProxy type normally isn't used directly - instead
proxies subclassing #GDBusProxy generated by <command><link
linkend="gdbus-codegen">gdbus-codegen</link></command> is used, see <xref linkend="gdbus-example-gdbus-codegen"/>
</para>
</section>
<section id="gdbus-example-gdbus-codegen">
<title>Using gdbus-codegen</title>
<para>
dbus-glib comes with <command>dbus-binding-tool</command>, which
can produce somewhat nice client- and server-side wrappers for a D-Bus interface.
With GDBus, <command><link
linkend="gdbus-codegen">gdbus-codegen</link></command> is used and like
its counterpart, it also takes D-Bus Introspection XML as input:
</para>
<example id="gdbus-example-codegen-input"><title>Example D-Bus Introspection XML</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../gdbus-example-objectmanager.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
<para>
If this XML is processed like this
<informalexample><programlisting><![CDATA[
gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
--generate-c-code generated-code \
--c-namespace Example \
--c-generate-object-manager \
--generate-docbook generated-docs \
gdbus-example-objectmanager.xml
]]></programlisting></informalexample>
then two files <filename>generated-code.h</filename> and
<filename>generated-code.c</filename> are
generated. Additionally, two XML files
<filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal</filename> and
<filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat</filename>
with Docbook XML are generated.
</para>
<para>
While the contents of <filename>generated-code.h</filename> and
<filename>generated-code.c</filename> are best described by the
<command><link
linkend="gdbus-codegen">gdbus-codegen</link></command> manual
page, brief examples of how this generated code can be used can be found in
<xref linkend="gdbus-example-codegen-server"/>
and <xref linkend="gdbus-example-codegen-client"/>.
</para>
</section>
</chapter>
docs/reference/gio/migrating-gnome-vfs.xml
+133
View File
@@ -0,0 +1,133 @@
<chapter>
<title>Migrating from GnomeVFS to GIO</title>
<table id="gnome-vfs-vs-gio">
<title>Comparison of GnomeVFS and GIO concepts</title>
<tgroup cols="2">
<thead>
<row><entry>GnomeVFS</entry><entry>GIO</entry></row>
</thead>
<tbody>
<row><entry>GnomeVFSURI</entry><entry>GFile</entry></row>
<row><entry>GnomeVFSFileInfo</entry><entry>GFileInfo</entry></row>
<row><entry>GnomeVFSResult</entry><entry>GError, with G_IO_ERROR values</entry></row>
<row><entry>GnomeVFSHandle &amp; GnomeVFSAsyncHandle</entry><entry>GInputStream or GOutputStream</entry></row>
<row><entry>GnomeVFSDirectoryHandle</entry><entry>GFileEnumerator</entry></row>
<row><entry>mime type</entry><entry>content type</entry></row>
<row><entry>GnomeVFSMonitor</entry><entry>GFileMonitor</entry></row>
<row><entry>GnomeVFSVolumeMonitor</entry><entry>GVolumeMonitor</entry></row>
<row><entry>GnomeVFSVolume</entry><entry>GMount</entry></row>
<row><entry>GnomeVFSDrive</entry><entry>GVolume</entry></row>
<row><entry>-</entry><entry>GDrive</entry></row>
<row><entry>GnomeVFSContext</entry><entry>GCancellable</entry></row>
<row><entry>gnome_vfs_async_cancel</entry><entry>g_cancellable_cancel</entry></row>
</tbody>
</tgroup>
</table>
<section>
<title>Trash handling</title>
<para>
The handling of trashed files has been changed in GIO, compared
to gnome-vfs. gnome-vfs has a home-grown trash implementation that
predates the freedesktop.org <ulink url="http://www.freedesktop.org/wiki/Specifications/trash-spec">Desktop Trash Can</ulink> specification
that is implemented in GIO. The location for storing trashed files
has changed from <filename>$HOME/.Trash</filename> to
<filename>$HOME/.local/share/Trash</filename> (or more correctly
<filename>$XDG_DATA_HOME/Trash</filename>), which means that
there is a need for migrating files that have been trashed by
gnome-vfs to the new location.
</para>
<para>
In gnome-vfs, the <filename>trash://</filename> scheme offering a
merged view of all trash directories was implemented in nautilus,
and trash-handling applications had to find and monitor all trash
directories themselves. With GIO, the <filename>trash://</filename>
implementation has been moved to gvfs and applications can simply
monitor that location:
</para>
<informalexample><programlisting>
static void
file_changed (GFileMonitor *file_monitor,
GFile *child,
GFile *other_file,
GFileMonitorEvent event_type,
gpointer user_data)
{
switch (event_type)
{
case G_FILE_MONITOR_EVENT_DELETED:
g_print ("'%s' removed from trash\n", g_file_get_basename (child));
break;
case G_FILE_MONITOR_EVENT_CREATED:
g_print ("'%s' added to trash\n", g_file_get_basename (child));
break;
default: ;
}
}
static void
start_monitoring_trash (void)
{
GFile *file;
GFileMonitor *monitor;
file = g_file_new_for_uri ("trash://");
monitor = g_file_monitor_directory (file, 0, NULL, NULL);
g_object_unref (file);
g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
/* ... */
}
</programlisting></informalexample>
<para>
GIO exposes some useful metadata about trashed files. There are
trash::orig-path and trash::deletion-date attributes. The
standard::icon attribute of the <filename>trash://</filename>
itself provides a suitable icon for displaying the trash can on
the desktop. If you are using this icon, make sure to monitor
this attribute for changes, since the icon may be updated to
reflect that state of the trash can.
</para>
<para>
Moving a file to the trash is much simpler with GIO. Instead of
using gnome_vfs_find_directory() with %GNOME_VFS_DIRECTORY_KIND_TRASH
to find out where to move the trashed file, just use the g_file_trash()
function.
</para>
</section>
<section>
<title>Operations on multiple files</title>
<para>
gnome-vfs has the dreaded gnome_vfs_xfer_uri_list() function which
has tons of options and offers the equivalent of cp, mv, ln, mkdir
and rm at the same time.
</para>
<para>
GIO offers a much simpler I/O scheduler functionality instead, that
lets you schedule a function to be called in a separate thread, or
if threads are not available, as an idle in the mainloop.
See g_io_scheduler_push_job().
</para>
</section>
<section>
<title>Mime monitoring</title>
<para>
gnome-vfs offered a way to monitor the association between mime types
and default handlers for changes, with the #GnomeVFSMIMEMonitor object.
GIO does not offer a replacement for this functionality at this time,
since we have not found a compelling use case where
#GnomeVFSMIMEMonitor was used. If you think you have such a use
case, please report it at
<ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
</para>
</section>
</chapter>
docs/reference/gio/migrating-posix.xml
+27
View File
@@ -0,0 +1,27 @@
<part id="migrating">
<title>Migrating to GIO</title>
<chapter>
<title>Migrating from POSIX to GIO</title>
<table id="posix-vs-gio">
<title>Comparison of POSIX and GIO concepts</title>
<tgroup cols="2">
<thead>
<row><entry>POSIX</entry><entry>GIO</entry></row>
</thead>
<tbody>
<row><entry>char *path</entry><entry>GFile *file</entry></row>
<row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
<row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
<row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
<row><entry>GOutputStream *out</entry></row>
<row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
<row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
<row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
</tbody>
</tgroup>
</table>
</chapter>
</part>
docs/reference/gio/overview.xml
+756
View File
@@ -0,0 +1,756 @@
<part>
<title>GIO Overview</title>
<chapter>
<title>Introduction</title>
<para>
GIO is striving to provide a modern, easy-to-use VFS API that sits
at the right level in the library stack, as well as other generally
useful APIs for desktop applications (such as networking and
D-Bus support). The goal is to overcome the shortcomings of GnomeVFS
and provide an API that is so good that developers prefer it over raw
POSIX calls. Among other things that means using GObject. It also means
not cloning the POSIX API, but providing higher-level, document-centric
interfaces.
</para>
<para>
The abstract file system model of GIO consists of a number of
interfaces and base classes for I/O and files:
<variablelist>
<varlistentry>
<term>GFile</term>
<listitem><para>reference to a file</para></listitem>
</varlistentry>
<varlistentry>
<term>GFileInfo</term>
<listitem><para>information about a file or filesystem</para></listitem>
</varlistentry>
<varlistentry>
<term>GFileEnumerator</term>
<listitem><para>list files in directories</para></listitem>
</varlistentry>
<varlistentry>
<term>GDrive</term>
<listitem><para>represents a drive</para></listitem>
</varlistentry>
<varlistentry>
<term>GVolume</term>
<listitem><para>represents a file system in an abstract way</para></listitem>
</varlistentry>
<varlistentry>
<term>GMount</term>
<listitem><para>represents a mounted file system</para></listitem>
</varlistentry>
</variablelist>
Then there is a number of stream classes, similar to the input and
output stream hierarchies that can be found in frameworks like Java:
<variablelist>
<varlistentry>
<term>GInputStream</term>
<listitem><para>read data</para></listitem>
</varlistentry>
<varlistentry>
<term>GOutputStream</term>
<listitem><para>write data</para></listitem>
</varlistentry>
<varlistentry>
<term>GIOStream</term>
<listitem><para>read and write data</para></listitem>
</varlistentry>
<varlistentry>
<term>GSeekable</term>
<listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
</varlistentry>
</variablelist>
There are interfaces related to applications and the types
of files they handle:
<variablelist>
<varlistentry>
<term>GAppInfo</term>
<listitem><para>information about an installed application</para></listitem>
</varlistentry>
<varlistentry>
<term>GIcon</term>
<listitem><para>abstract type for file and application icons</para></listitem>
</varlistentry>
</variablelist>
There is a framework for storing and retrieving application settings:
<variablelist>
<varlistentry>
<term>GSettings</term>
<listitem><para>stores and retrieves application settings</para></listitem>
</varlistentry>
</variablelist>
There is support for network programming, including connectivity monitoring,
name resolution, lowlevel socket APIs and highlevel client and server
helper classes:
<variablelist>
<varlistentry>
<term>GSocket</term>
<listitem><para>lowlevel platform independent socket object</para></listitem>
</varlistentry>
<varlistentry>
<term>GResolver</term>
<listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketClient</term>
<listitem><para>high-level network client helper</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketService</term>
<listitem><para>high-level network server helper</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketConnection</term>
<listitem><para>network connection stream</para></listitem>
</varlistentry>
<varlistentry>
<term>GNetworkMonitor</term>
<listitem><para>network connectivity monitoring</para></listitem>
</varlistentry>
</variablelist>
There is support for connecting to <ulink url="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
sending and receiving messages, owning and watching bus names,
and making objects available on the bus:
<variablelist>
<varlistentry>
<term>GDBusConnection</term>
<listitem><para>a D-Bus connection</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusMethodInvocation</term>
<listitem><para>for handling remote calls</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusServer</term>
<listitem><para>helper for accepting connections</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusProxy</term>
<listitem><para>proxy to access D-Bus interfaces on a remote object</para></listitem>
</varlistentry>
</variablelist>
Beyond these, GIO provides facilities for file monitoring,
asynchronous I/O and filename completion. In addition to the
interfaces, GIO provides implementations for the local case.
Implementations for various network file systems are provided
by the GVFS package as loadable modules.
</para>
<para>
Other design choices which consciously break with the GnomeVFS
design are to move backends out-of-process, which minimizes the
dependency bloat and makes the whole system more robust. The backends
are not included in GIO, but in the separate GVFS package. The GVFS
package also contains the GVFS daemon, which spawn further mount
daemons for each individual connection.
</para>
<figure id="gvfs-overview">
<title>GIO in the GTK+ library stack</title>
<graphic fileref="gvfs-overview.png" format="PNG"></graphic>
</figure>
<para>
The GIO model of I/O is stateful: if an application establishes e.g.
a SFTP connection to a server, it becomes available to all applications
in the session; the user does not have to enter his password over
and over again.
</para>
<para>
One of the big advantages of putting the VFS in the GLib layer
is that GTK+ can directly use it, e.g. in the filechooser.
</para>
</chapter>
<chapter>
<title>Writing GIO applications</title>
<para>
The information in the GLib <ulink url="http://developer.gnome.org/glib/stable/glib-programming.html">documentation</ulink> about writing GLib
applications is generally applicable when writing GIO applications.
</para>
<simplesect><title>Threads</title>
<para>
GDBus has its own private worker thread, so applications using
GDBus have at least 3 threads. GIO makes heavy use of the concept
of a <link linkend="g-main-context-push-thread-default">thread-default
main context</link> to execute callbacks of asynchronous
methods in the same context in which the operation was started.
</para>
</simplesect>
<simplesect id="async-programming"><title>Asynchronous Programming</title>
<para>
Many GIO functions come in two versions: synchronous and asynchronous,
denoted by an <code>_async</code> suffix. It is important to use these
appropriately: synchronous calls should not be used from
within a main loop which is shared with other code, such as one in the
application’s main thread. Synchronous calls block until they complete,
and I/O operations can take noticeable amounts of time (even on ‘fast’
SSDs). Blocking a main loop iteration while waiting for I/O means that
other sources in the main loop will not be dispatched, such as input and
redraw handlers for the application’s UI. This can cause the application
to ‘freeze’ until I/O completes.
</para>
<para>
A few self-contained groups of functions, such as code generated by
<link linkend="gdbus-codegen"><application>gdbus-codegen</application></link>,
use a different convention: functions are asynchronous default, and it is
the <emphasis>synchronous</emphasis> version which has a
<code>_sync</code>
suffix. Aside from naming differences, they should be treated the same
way as functions following the normal convention above.
</para>
<para>
The asynchronous (<code>_async</code>) versions of functions return
control to the caller immediately, after scheduling the I/O in the kernel
and adding a callback for it to the main loop. This callback will be
invoked when the operation has completed. From the callback, the paired
<code>_finish</code> function should be called to retrieve the return
value of the I/O operation, and any errors which occurred. For more
information on using and implementing asynchronous functions, see
<link linkend="GAsyncResult.description"><type>GAsyncResult</type></link>
and <link linkend="GTask.description"><type>GTask</type></link>.
</para>
<para>
By starting multiple asynchronous operations in succession, they will be
executed in parallel (up to an arbitrary limit imposed by GIO’s internal
worker thread pool).
</para>
<para>
The synchronous versions of functions can be used early in application
startup when there is no main loop to block, for example to load initial
configuration files. They can also be used for I/O on files which are
guaranteed to be small and on the local disk. Note that the user’s home
directory is not guaranteed to be on the local disk.
</para>
</simplesect>
<simplesect><title>Security</title>
<para>
When your program needs to carry out some privileged operation (say,
create a new user account), there are various ways in which you can go
about this:
<itemizedlist>
<listitem><para>
Implement a daemon that offers the privileged operation. A convenient
way to do this is as a D-Bus system-bus service. The daemon will probably
need ways to check the identity and authorization of the caller before
executing the operation. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> is a framework that allows this.
</para></listitem>
<listitem><para>
Use a small helper that is executed with elevated privileges via
pkexec. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html">pkexec</ulink> is a small program launcher that is part of polkit.
</para></listitem>
<listitem><para>
Use a small helper that is executed with elevated privileges by
being suid root.
</para></listitem>
</itemizedlist>
None of these approaches is the clear winner, they all have their
advantages and disadvantages.
</para>
<para>
When writing code that runs with elevated privileges, it is important
to follow some basic rules of secure programming. David Wheeler has an
excellent book on this topic,
<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
</para>
<para>
When using GIO in code that runs with elevated privileges, you have to
be careful. GIO has extension points whose implementations get loaded
from modules (executable code in shared objects), which could allow
an attacker to sneak his own code into your application by tricking it
into loading the code as a module. However, GIO will never load modules
from your home directory except when explictly asked to do so via an
environment variable.
</para>
<para>
In most cases, your helper program should be so small that you don't
need GIO, whose APIs are largely designed to support full-blown desktop
applications. If you can't resist the convenience of these APIs, here
are some steps you should take:
<itemizedlist>
<listitem><para>
Clear the environment, e.g. using the <function>clearenv()</function>
function.
David Wheeler has a good <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html">explanation</ulink> for why it is
important to sanitize the environment.
See <xref linkend="running-gio-apps"/>
for a list of all environment variables affecting GIO. In particular,
<envar>PATH</envar> (used to locate binaries), <envar>GIO_EXTRA_MODULES</envar> (used to locate loadable modules) and <envar>DBUS_{SYSTEM,SESSION}_BUS_ADDRESS</envar> (used to locate the D-Bus system and session bus) are important.
</para></listitem>
<listitem><para>
Don't use GVfs, by setting <envar>GIO_USE_VFS=local</envar> in the environment.
The reason to avoid GVfs in security-sensitive programs is that it uses
many libraries which have not necessarily been audited for security problems.
Gvfs is also heavily distributed and relies on a session bus to be present.
</para></listitem>
</itemizedlist>
</para>
</simplesect>
</chapter>
<chapter>
<title>Compiling GIO applications</title>
<para>
GIO comes with a <filename>gio-2.0.pc</filename> file that you
should use together with <literal>pkg-config</literal> to obtain
the necessary information about header files and libraries. See
the <literal>pkg-config</literal> man page or the GLib documentation
for more information on how to use <literal>pkg-config</literal>
to compile your application.
</para>
<para>
If you are using GIO on UNIX-like systems, you may want to use
UNIX-specific GIO interfaces such as #GUnixInputStream,
#GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
To do so, use the <filename>gio-unix-2.0.pc</filename> file
instead of <filename>gio-2.0.pc</filename>
</para>
</chapter>
<chapter id="running-gio-apps">
<title>Running GIO applications</title>
<para>
GIO inspects a few environment variables in addition to the
ones used by GLib.
</para>
<formalpara>
<title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
<para>
GIO uses these environment variables to locate MIME information.
For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
</para>
</formalpara>
<formalpara>
<title><envar>GVFS_DISABLE_FUSE</envar></title>
<para>
This variable can be set to keep #Gvfs from starting the fuse backend,
which may be unwanted or unnecessary in certain situations.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_USE_VFS</envar></title>
<para>
This environment variable can be set to the name of a #GVfs
implementation to override the default for debugging purposes.
The #GVfs implementation for local files that is included in GIO
has the name "local", the implementation in the gvfs module has
the name "gvfs". Most commonly, system software will set this to "local"
to avoid having `GFile` APIs perform unnecessary DBus calls.
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<para>
The following environment variables are only useful for debugging
GIO itself or modules that it loads. They should not be set in a
production environment.
</para>
<formalpara>
<title><envar>GIO_USE_FILE_MONITOR</envar></title>
<para>
This variable can be set to the name of a #GFileMonitor
implementation to override the default for debugging purposes.
The #GFileMonitor implementation for local files that is included
in GIO on Linux has the name "inotify", others that are built
are built as modules (depending on the platform) are called
"fam" and "fen".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
<para>
This variable can be set to the name of a #GVolumeMonitor
implementation to override the default for debugging purposes.
The #GVolumeMonitor implementation for local files that is included
in GIO has the name "unix", the udisks2-based implementation in the
gvfs module has the name "udisks2".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_USE_TLS</envar></title>
<para>
This variable can be set to the name of a #GTlsBackend
implementation to override the default for debugging purposes.
GIO does not include a #GTlsBackend implementation, the gnutls-based
implementation in the glib-networking module has the name "gnutls".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_MODULE_DIR</envar></title>
<para>
When this environment variable is set to a path, GIO will load
modules from this alternate directory instead of the directory
built into GIO. This is useful when running tests, for example.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_EXTRA_MODULES</envar></title>
<para>
When this environment variable is set to a path, or a set of
paths separated by a colon, GIO will attempt to load
additional modules from within the path.
</para>
</formalpara>
<formalpara>
<title><envar>GSETTINGS_BACKEND</envar></title>
<para>
This variable can be set to the name of a #GSettingsBackend
implementation to override the default for debugging purposes.
The memory-based implementation that is included in GIO has
the name "memory", the one in dconf has the name "dconf".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
<para>
This variable can be set to the name of a directory that is
considered in addition to the <filename>glib-2.0/schemas</filename>
subdirectories of the XDG system data dirs when looking
for compiled schemas for #GSettings.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_SYSTEM_BUS_ADDRESS</envar></title>
<para>
This variable is consulted to find the address of the D-Bus system
bus. For the format of D-Bus addresses, see the D-Bus
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
</para>
<para>
Setting this variable overrides platform-specific ways of determining
the system bus address.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
<para>
This variable is consulted to find the address of the D-Bus session bus.
</para>
<para>
Setting this variable overrides platform-specific ways of determining
the session bus address.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
<para>
This variable is consulted to find out the 'starter' bus for an
application that has been started via D-Bus activation. The possible
values are 'system' or 'session'.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_DEBUG</envar></title>
<para>
This variable can be set to a list of debug options, which
cause GLib to print out different types of debugging
information when using the D-Bus routines.
<variablelist>
<varlistentry>
<term>transport</term>
<listitem><para>Show IO activity (e.g. reads and writes)</para></listitem>
</varlistentry>
<varlistentry>
<term>message</term>
<listitem><para>Show all sent and received D-Bus messages</para></listitem>
</varlistentry>
<varlistentry>
<term>payload</term>
<listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
</varlistentry>
<varlistentry>
<term>call</term>
<listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
</varlistentry>
<varlistentry>
<term>signal</term>
<listitem><para>Show when a D-Bus signal is received</para></listitem>
</varlistentry>
<varlistentry>
<term>incoming</term>
<listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
</varlistentry>
<varlistentry>
<term>return</term>
<listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
</varlistentry>
<varlistentry>
<term>emission</term>
<listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
</varlistentry>
<varlistentry>
<term>authentication</term>
<listitem><para>Show information about connection authentication</para></listitem>
</varlistentry>
<varlistentry>
<term>address</term>
<listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
</varlistentry>
</variablelist>
The special value <literal>all</literal> can be used to turn
on all debug options. The special value
<literal>help</literal> can be used to print a list of
supported options to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
<para>
Can be used to override the directory used to store the
keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
authentication mechanism. Normally the directory used is
<filename>.dbus-keyrings</filename> in the user's home
directory.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
<para>
If set, the permissions of the directory used to store the
keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
authentication mechanism won't be checked. Normally the
directory must be readable only by the user.
</para>
</formalpara>
</chapter>
<chapter id="extending-gio">
<title>Extending GIO</title>
<para>
A lot of the functionality that is accessible through GIO
is implemented in loadable modules, and modules provide a convenient
way to extend GIO. In addition to the #GIOModule API which supports
writing such modules, GIO has a mechanism to define extension points,
and register implementations thereof, see #GIOExtensionPoint.
</para>
<para>
The following extension points are currently defined by GIO:
</para>
<formalpara>
<title>G_VFS_EXTENSION_POINT_NAME</title>
<para>
Allows to override the functionality of the #GVfs class.
Implementations of this extension point must be derived from #GVfs.
GIO uses the implementation with the highest priority that is active,
see g_vfs_is_active().
</para>
<para>
GIO implements this extension point for local files, gvfs contains
an implementation that supports all the backends in gvfs.
</para>
</formalpara>
<formalpara>
<title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to add more volume monitors.
Implementations of this extension point must be derived from
#GVolumeMonitor. GIO uses all registered extensions.
</para>
<para>
gvfs contains an implementation that works together with the #GVfs
implementation in gvfs.
</para>
</formalpara>
<formalpara>
<title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to override the 'native' volume monitor.
Implementations of this extension point must be derived from
#GNativeVolumeMonitor. GIO uses the implementation with
the highest priority that is supported, as determined by the
is_supported() vfunc in #GVolumeMonitorClass.
</para>
<para>
GIO implements this extension point for local mounts,
gvfs contains a udisks2-based implementation.
</para>
</formalpara>
<formalpara>
<title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to override the file monitor implementation for
local files. Implementations of this extension point must
be derived from #GLocalFileMonitor. GIO uses the implementation
with the highest priority that is supported, as determined by the
is_supported() vfunc in #GLocalFileMonitorClass.
</para>
<para>
GIO uses this extension point internally, to switch between
its fam-based and inotify-based file monitoring implementations.
</para>
</formalpara>
<formalpara>
<title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to override the directory monitor implementation for
local files. Implementations of this extension point must be
derived from #GLocalDirectoryMonitor. GIO uses the implementation
with the highest priority that is supported, as determined by the
is_supported() vfunc in #GLocalDirectoryMonitorClass.
</para>
<para>
GIO uses this extension point internally, to switch between
its fam-based and inotify-based directory monitoring implementations.
</para>
</formalpara>
<formalpara>
<title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
<para>
Unix-only. Allows to provide a way to associate default handlers
with URI schemes. Implementations of this extension point must
implement the #GDesktopAppInfoLookup interface. GIO uses the
implementation with the highest priority.
</para>
<para>
This extension point has been discontinued in GLib 2.28. It is
still available to keep API and ABI stability, but GIO is no
longer using it for default handlers. Instead, the mime handler
mechanism is used, together with x-scheme-handler pseudo-mimetypes.
</para>
</formalpara>
<formalpara>
<title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
<para>
Allows to provide an alternative storage for #GSettings.
Implementations of this extension point must derive from the
#GSettingsBackend type. GIO contains a keyfile-based
implementation of this extension point, another one is provided
by dconf.
</para>
</formalpara>
<formalpara>
<title>G_PROXY_EXTENSION_POINT_NAME</title>
<para>
Allows to provide implementations for network proxying.
Implementations of this extension point must provide the
#GProxy interface, and must be named after the network
protocol they are proxying.
</para>
<para>
glib-networking contains an implementation of this extension
point based on libproxy.
</para>
</formalpara>
<formalpara>
<title>G_TLS_BACKEND_EXTENSION_POINT_NAME</title>
<para>
Allows to provide implementations for TLS support.
Implementations of this extension point must implement
the #GTlsBackend interface.
</para>
<para>
glib-networking contains an implementation of this extension
point.
</para>
</formalpara>
<formalpara>
<title>G_NETWORK_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to provide implementations for network connectivity
monitoring.
Implementations of this extension point must implement
the #GNetworkMonitorInterface interface.
</para>
<para>
GIO contains an implementation of this extension point
that is using the netlink interface of the Linux kernel.
</para>
</formalpara>
</chapter>
</part>
docs/reference/gio/version.xml.in
+1
View File
@@ -0,0 +1 @@
@VERSION@
docs/reference/glib/Sorted_binary_tree_breadth-first_traversal.svg
+134
View File
@@ -0,0 +1,134 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 16.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
width="266px" height="212px" viewBox="0 0 266 212" enable-background="new 0 0 266 212" xml:space="preserve">
<g>
<g>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" x1="27.23" y1="23.192" x2="29.23" y2="23.192"/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9562,3.9562" x1="33.187" y1="23.192" x2="236.932" y2="23.192"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,23.192 240.91,23.192
238.97,23.677 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="24.646" x2="27.971" y2="76.427"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,76.912 24.095,77.396
26.095,77.396 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0154,4.0154" x1="30.11" y1="77.396" x2="236.902" y2="77.396"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,77.396 240.91,77.396
238.97,77.881 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="78.85" x2="27.971" y2="130.631"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,131.114 24.095,131.6
26.095,131.6 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0154,4.0154" x1="30.11" y1="131.6" x2="236.902" y2="131.6"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,131.6 240.91,131.6
238.97,132.085 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="133.053" x2="27.971" y2="184.835"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,185.318 24.095,185.804
26.095,185.804 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0086,4.0086" x1="30.104" y1="185.804" x2="228.53" y2="185.804"/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" x1="230.534" y1="185.804" x2="232.534" y2="185.804"/>
<g>
<rect x="24.095" y="19.892" width="6.602" height="6.602"/>
</g>
<g>
<path d="M238.569,185.804c-2.84,1.054-6.363,2.852-8.548,4.756l1.721-4.756l-1.721-4.755
C232.206,182.953,235.729,184.751,238.569,185.804z"/>
</g>
</g>
</g>
<g id="graph0">
<title>sorted_binary_tree</title>
<g id="node1">
<title>C</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="60.23" cy="185.804" rx="18.067" ry="18.067"/>
<text transform="matrix(1 0 0 1 55.5435 190.8223)" font-family="'Times-Roman'" font-size="14.0528">C</text>
</g>
<g id="node2">
<title>E</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="132.502" cy="185.804" rx="18.067" ry="18.067"/>
<text transform="matrix(1 0 0 1 128.21 190.8223)" font-family="'Times-Roman'" font-size="14.0528">E</text>
</g>
<g id="node3">
<title>H</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="204.773" cy="185.804" rx="17.064" ry="18.067"/>
<text transform="matrix(1 0 0 1 199.6992 190.8223)" font-family="'Times-Roman'" font-size="14.0528">H</text>
</g>
<g id="node4">
<title>A</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="24.094" cy="131.6" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 19.02 136.6191)" font-family="'Times-Roman'" font-size="14.0528">A</text>
</g>
<g id="node5">
<title>D</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="96.366" cy="131.6" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 91.292 136.6191)" font-family="'Times-Roman'" font-size="14.0528">D</text>
</g>
<g id="edge6">
<title>D-&gt;C</title>
<path fill="none" stroke="#000000" d="M86.328,147.66c-3.011,4.016-7.026,9.034-10.038,14.053"/>
<polygon stroke="#000000" points="78.298,164.725 70.268,170.747 73.279,160.709 "/>
</g>
<g id="edge8">
<title>D-&gt;E</title>
<path fill="none" stroke="#000000" d="M106.404,147.66c3.011,4.016,7.026,9.034,10.038,14.053"/>
<polygon stroke="#000000" points="119.453,160.709 122.464,170.747 114.434,164.725 "/>
</g>
<g id="node6">
<title>I</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="240.909" cy="131.6" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 238.5693 136.6191)" font-family="'Times-Roman'" font-size="14.0528">I</text>
</g>
<g id="edge12">
<title>I-&gt;H</title>
<path fill="none" stroke="#000000" d="M230.871,146.656c-3.011,5.02-6.021,10.038-10.037,15.057"/>
<polygon stroke="#000000" points="223.846,163.721 214.812,169.743 217.822,159.705 "/>
</g>
<g id="node7">
<title>B</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="60.23" cy="77.396" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 55.5435 82.415)" font-family="'Times-Roman'" font-size="14.0528">B</text>
</g>
<g id="edge3">
<title>B-&gt;A</title>
<path fill="none" stroke="#000000" d="M50.192,92.453c-3.011,5.019-6.022,10.038-10.038,15.057"/>
<polygon stroke="#000000" points="43.166,109.518 34.132,115.539 37.144,105.502 "/>
</g>
<g id="edge5">
<title>B-&gt;D</title>
<path fill="none" stroke="#000000" d="M70.268,92.453c3.011,5.019,6.022,10.038,10.038,15.057"/>
<polygon stroke="#000000" points="83.317,105.502 86.328,115.539 77.294,109.518 "/>
</g>
<g id="node8">
<title>G</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="204.773" cy="77.396" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 199.6992 82.415)" font-family="'Times-Roman'" font-size="14.0528">G</text>
</g>
<g id="edge11">
<title>G-&gt;I</title>
<path fill="none" stroke="#000000" d="M214.812,93.457c3.011,4.015,7.026,9.034,10.038,14.053"/>
<polygon stroke="#000000" points="227.86,106.506 230.871,116.543 222.842,110.521 "/>
</g>
<g id="node9">
<title>F</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="132.502" cy="23.192" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 128.5942 28.2109)" font-family="'Times-Roman'" font-size="14.0528">F</text>
</g>
<g id="edge2">
<title>F-&gt;B</title>
<path fill="none" stroke="#000000" d="M117.445,34.234c-11.042,8.03-23.087,17.064-34.128,26.098"/>
<polygon stroke="#000000" points="85.325,63.343 75.287,66.354 81.31,57.321 "/>
</g>
<g id="edge10">
<title>F-&gt;G</title>
<path fill="none" stroke="#000000" d="M147.559,34.234c11.041,8.03,23.087,17.064,34.129,26.098"/>
<polygon stroke="#000000" points="183.694,57.321 189.717,66.354 179.68,63.343 "/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

docs/reference/glib/Sorted_binary_tree_inorder.svg
+753
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

docs/reference/glib/Sorted_binary_tree_postorder.svg
+750
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

docs/reference/glib/Sorted_binary_tree_preorder.svg
+750
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

docs/reference/glib/building.xml
+385
View File
@@ -0,0 +1,385 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-building">
<refmeta>
<refentrytitle>Compiling the GLib package</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Compiling the GLib Package</refname>
<refpurpose>How to compile GLib itself</refpurpose>
</refnamediv>
<refsect1 id="building">
<title>Building the Library on UNIX</title>
<para>
On UNIX, GLib uses the standard <application>Meson</application> build
system. The normal sequence for compiling and installing the GLib library
is thus:
<literallayout>
<userinput>meson _build</userinput>
<userinput>ninja -C _build</userinput>
<userinput>ninja -C _build install</userinput>
</literallayout>
</para>
<para>
The standard options provided by <application>Meson</application> may be
passed to the <command>meson</command> command. Please see the
<application>Meson</application> documentation or run
<command>meson configure --help</command> for information about
the standard options.
</para>
<para>
GLib is compiled with
<ulink url="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing">strict aliasing</ulink>
disabled. It is strongly recommended that this is not re-enabled by
overriding the compiler flags, as GLib has not been tested with strict
aliasing and cannot be guaranteed to work.
</para>
<para>
The GTK+ documentation contains
<ulink url="https://developer.gnome.org/gtk3/stable/gtk-building.html">further details</ulink>
about the build process and ways to influence it.
</para>
</refsect1>
<refsect1 id="dependencies">
<title>Dependencies</title>
<para>
Before you can compile the GLib library, you need to have
various other tools and libraries installed on your system.
If you are building from a release archive, you will need
<ulink url="https://wiki.gnome.org/Projects/GLib/CompilerRequirements">a compliant C toolchain</ulink>,
<application>Meson</application>, and <application>pkg-config</application>;
the requirements are the same when building from a Git repository clone
of GLib.
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
is a tool for tracking the compilation flags needed for
libraries that are used by the GLib library. (For each
library, a small <literal>.pc</literal> text file is
installed in a standard location that contains the compilation
flags needed for that library along with version number
information).
</para>
</listitem>
</itemizedlist>
<para>
A UNIX build of GLib requires that the system implements at
least the original 1990 version of POSIX. Beyond this, it
depends on a number of other libraries.
</para>
<itemizedlist>
<listitem>
<para>
The <ulink url="http://www.gnu.org/software/libiconv/">GNU
libiconv library</ulink> is needed to build GLib if your
system doesn't have the <function>iconv()</function>
function for doing conversion between character
encodings. Most modern systems should have
<function>iconv()</function>, however many older systems lack
an <function>iconv()</function> implementation. On such systems,
you must install the libiconv library. This can be found at:
<ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
</para>
<para>
If your system has an <function>iconv()</function> implementation but
you want to use libiconv instead, you can pass the
<option>-Diconv=gnu</option> option to <command>meson</command>. This
forces libiconv to be used.
</para>
<para>
Note that if you have libiconv installed in your default include
search path (for instance, in <filename>/usr/local/</filename>), but
don't enable it, you will get an error while compiling GLib because
the <filename>iconv.h</filename> that libiconv installs hides the
system iconv.
</para>
<para>
If you are using the native iconv implementation on Solaris
instead of libiconv, you'll need to make sure that you have
the converters between locale encodings and UTF-8 installed.
At a minimum you'll need the SUNWuiu8 package. You probably
should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
SUNWkiu8 packages.
</para>
<para>
The native iconv on Compaq Tru64 doesn't contain support for
UTF-8, so you'll need to use GNU libiconv instead. (When
using GNU libiconv for GLib, you'll need to use GNU libiconv
for GNU gettext as well.) This probably applies to related
operating systems as well.
</para>
</listitem>
<listitem>
<para>
The libintl library from the <ulink
url="http://www.gnu.org/software/gettext">GNU gettext
package</ulink> is needed if your system doesn't have the
<function>gettext()</function> functionality for handling
message translation databases.
</para>
</listitem>
<listitem>
<para>
A thread implementation is needed. The thread support in GLib
can be based upon POSIX threads or win32 threads.
</para>
</listitem>
<listitem>
<para>
GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
for regular expression matching. The default is to use the system
version of PCRE, to reduce the chances of security fixes going out
of sync. GLib additionally provides an internal copy of PCRE in case
the system version is too old, or does not support UTF-8; the internal
copy is patched to use GLib for memory management and to share the
same Unicode tables.
</para>
</listitem>
<listitem>
<para>
The optional extended attribute support in GIO requires the
<function>getxattr()</function> family of functions that may be
provided by the C library or by the standalone libattr library. To
build GLib without extended attribute support, use the
<option>-Dxattr=false</option> option.
</para>
</listitem>
<listitem>
<para>
The optional SELinux support in GIO requires libselinux.
To build GLib without SELinux support, use the
<option>-Dselinux=disabled</option> option.
</para>
</listitem>
<listitem>
<para>
The optional support for DTrace requires the
<filename>sys/sdt.h</filename> header, which is provided
by SystemTap on Linux. To build GLib without DTrace, use
the <option>-Ddtrace=false</option> option.
</para>
</listitem>
<listitem>
<para>
The optional support for
<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
can be disabled with the <option>-Dsystemtap=false</option>
option. Additionally, you can control the location
where GLib installs the SystemTap probes, using the
<option>-Dtapset_install_dir=DIR</option> option.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 id="extra-configuration-options">
<title>Extra Configuration Options</title>
<para>
In addition to the normal options, these additional ones are supported
when configuring the GLib library:
</para>
<formalpara>
<title><option>--buildtype</option></title>
<para>
This is a standard <application>Meson</application> option which
specifies how much debugging and optimization to enable. If the build
type starts with <literal>debug</literal>,
<literal>G_ENABLE_DEBUG</literal> will be defined and GLib will be built
with additional debug code enabled.
</para>
</formalpara>
<formalpara>
<title><option>-Dforce_posix_threads=true</option></title>
<para>
Normally, <application>Meson</application> should be able to work out
the correct thread implementation to use. This option forces POSIX
threads to be used even if the platform provides another threading API
(for example, on Windows).
</para>
</formalpara>
<formalpara>
<title><option>-Dinternal_pcre=true</option></title>
<para>
Normally, GLib will be configured to use the system-supplied PCRE
library if it is suitable, falling back to an internal version
otherwise. If this option is specified, the internal version will always
be used.
</para>
<para>
Using the internal PCRE is the preferred solution if:
<itemizedlist>
<listitem>
<para>
your system has strict resource constraints; the system-supplied
PCRE has a separated copy of the tables used for Unicode
handling, whereas the internal copy shares the Unicode tables
used by GLib.
</para>
</listitem>
<listitem>
<para>
your system has PCRE built without some needed features,
such as UTF-8 and Unicode support.
</para>
</listitem>
<listitem>
<para>
you are planning to use both GRegex and PCRE API at the same
time, either directly or indirectly through a dependency; PCRE
uses some global variables for memory management and
other features, and if both GLib and PCRE try to access them
at the same time, this could lead to undefined behavior.
</para>
</listitem>
</itemizedlist>
</para>
</formalpara>
<formalpara>
<title><option>-Dbsymbolic_functions=false</option> and
<option>-Dbsymbolic_functions=true</option></title>
<para>
By default, GLib uses the <option>-Bsymbolic-functions</option>
linker flag to avoid intra-library PLT jumps. A side-effect
of this is that it is no longer possible to override
internal uses of GLib functions with
<envar>LD_PRELOAD</envar>. Therefore, it may make
sense to turn this feature off in some situations.
The <option>-Dbsymbolic_functions=false</option> option allows
to do that.
</para>
</formalpara>
<formalpara>
<title><option>-Dgtk_doc=false</option> and
<option>-Dgtk_doc=true</option></title>
<para>
By default, GLib will detect whether the
<application>gtk-doc</application> package is installed.
If it is, then it will use it to extract and build the
documentation for the GLib library. These options
can be used to explicitly control whether
<application>gtk-doc</application> should be
used or not. If it is not used, the distributed,
pre-generated HTML files will be installed instead of
building them on your machine.
</para>
</formalpara>
<formalpara>
<title><option>-Dman=false</option> and
<option>-Dman=true</option></title>
<para>
By default, GLib will detect whether <application>xsltproc</application>
and the necessary DocBook stylesheets are installed.
If they are, then it will use them to rebuild the included
man pages from the XML sources. These options can be used
to explicitly control whether man pages should be rebuilt
used or not. The distribution includes pre-generated man
pages.
</para>
</formalpara>
<formalpara>
<title><option>-Dxattr=false</option> and
<option>-Dxattr=true</option></title>
<para>
By default, GLib will detect whether the
<function>getxattr()</function>
family of functions is available. If it is, then extended
attribute support will be included in GIO. These options can
be used to explicitly control whether extended attribute
support should be included or not. <function>getxattr()</function>
and friends can be provided by glibc or by the standalone
libattr library.
</para>
</formalpara>
<formalpara>
<title><option>-Dselinux=auto</option>,
<option>-Dselinux=enabled</option> or
<option>-Dselinux=disabled</option></title>
<para>
By default, GLib will detect if libselinux is available and
include SELinux support in GIO if it is. These options can be
used to explicitly control whether SELinux support should
be included.
</para>
</formalpara>
<formalpara>
<title><option>-Ddtrace=false</option> and
<option>-Ddtrace=true</option></title>
<para>
By default, GLib will detect if DTrace support is available, and use it.
These options can be used to explicitly control whether DTrace support
is compiled into GLib.
</para>
</formalpara>
<formalpara>
<title><option>-Dsystemtap=false</option> and
<option>-Dsystemtap=true</option></title>
<para>
This option requires DTrace support. If it is available, then
GLib will also check for the presence of SystemTap.
</para>
</formalpara>
<formalpara>
<title><option>-Db_coverage=true</option> and
<option>-Db_coverage=false</option></title>
<para>
Enable the generation of coverage reports for the GLib tests.
This requires the lcov frontend to gcov from the
<ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
To generate a coverage report, use
<command>ninja coverage-html</command>. The report is placed in the
<filename>meson-logs</filename> directory.
</para>
</formalpara>
<formalpara>
<title><option>-Druntime_libdir=RELPATH</option></title>
<para>
Allows specifying a relative path to where to install the runtime
libraries (meaning library files used for running, not developing,
GLib applications). This can be used in operating system setups where
programs using GLib needs to run before e.g. <filename>/usr</filename>
is mounted.
For example, if <varname>LIBDIR</varname> is <filename>/usr/lib</filename> and
<filename>../../lib</filename> is passed to
<option>-Druntime_libdir</option> then the
runtime libraries are installed into <filename>/lib</filename> rather
than <filename>/usr/lib</filename>.
</para>
</formalpara>
</refsect1>
</refentry>
docs/reference/glib/changes.xml
+174
View File
@@ -0,0 +1,174 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-changes" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Changes to GLib</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Changes to GLib</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Changes to GLib</refname>
<refpurpose>
Incompatible changes made between successing versions of GLib
</refpurpose>
</refnamediv>
<refsect1>
<title>Incompatible changes from 2.0 to 2.2</title>
<itemizedlist>
<listitem>
<para>
GLib changed the seeding algorithm for the pseudo-random number
generator Mersenne Twister, as used by <structname>GRand</structname>
and <structname>GRandom</structname>. This was necessary, because some
seeds would yield very bad pseudo-random streams. Also the
pseudo-random integers generated by
<function>g_rand*_int_range()</function> will have a
slightly better equal distribution with the new version of GLib.
</para>
<para>
Further information can be found at the website of the Mersenne
Twister random number generator at <ulink
url="http://www.math.keio.ac.jp/~matumoto/emt.html">http://www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
</para>
<para>
The original seeding and generation algorithms, as found in GLib
2.0.x, can be used instead of the new ones by setting the environment
variable <envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use
the GLib-2.0 algorithms only if you have sequences of numbers generated
with Glib-2.0 that you need to reproduce exactly.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>Incompatible changes from 1.2 to 2.0</title>
<itemizedlist>
<listitem>
<para>
The event loop functionality <structname>GMain</structname> has extensively
been revised to support multiple separate main loops in separate threads.
All sources (timeouts, idle functions, etc.) are associated with a
<structname>GMainContext</structname>.
</para>
<para>
Compatibility functions exist so that most application code dealing with
the main loop will continue to work. However, code that creates new custom
types of sources will require modification.
</para>
<para>
The main changes here are:
<itemizedlist>
<listitem>
<para>
Sources are now exposed as <type>GSource *</type>, rather than simply as
numeric ids.
</para>
</listitem>
<listitem>
<para>
New types of sources are created by structure "derivation" from
<structname>GSource</structname>, so the <literal>source_data</literal>
parameter to the <structname>GSource</structname> virtual functions has been
replaced with a <type>GSource *</type>.
</para>
</listitem>
<listitem>
<para>
Sources are first created, then later added to a specific
<structname>GMainContext</structname>.
</para>
</listitem>
<listitem>
<para>
Dispatching has been modified so both the callback and data are passed
in to the <function>dispatch()</function> virtual function.
</para>
</listitem>
</itemizedlist>
To go along with this change, the vtable for
<structname>GIOChannel</structname> has changed and
<function>add_watch()</function> has been replaced by
<function>create_watch()</function>.
</para>
</listitem>
<listitem>
<para>
<function>g_list_foreach()</function> and
<function>g_slist_foreach()</function> have been changed so they
are now safe against removal of the current item, not the next item.
</para>
<para>
It's not recommended to mutate the list in the callback to these
functions in any case.
</para>
</listitem>
<listitem>
<para>
<structname>GDate</structname> now works in UTF-8, not in the current locale.
If you want to use it with the encoding of the locale, you need to convert
strings using <function>g_locale_to_utf8()</function> first.
</para>
</listitem>
<listitem>
<para>
<function>g_strsplit()</function> has been fixed to:
<itemizedlist>
<listitem>
<para>
include trailing empty tokens, rather than stripping them
</para>
</listitem>
<listitem>
<para>
split into a maximum of <literal>max_tokens</literal> tokens, rather
than <literal>max_tokens + 1</literal>
</para>
</listitem>
</itemizedlist>
Code depending on either of these bugs will need to be fixed.
</para>
</listitem>
<listitem>
<para>
Deprecated functions that got removed:
<function>g_set_error_handler()</function>,
<function>g_set_warning_handler()</function>,
<function>g_set_message_handler()</function>, use
<function>g_log_set_handler()</function> instead.
</para>
</listitem>
</itemizedlist>
</refsect1>
</refentry>
docs/reference/glib/compiling.xml
+125
View File
@@ -0,0 +1,125 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-compiling" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Compiling GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Compiling GLib Applications</refname>
<refpurpose>
How to compile your GLib application
</refpurpose>
</refnamediv>
<refsect1>
<title>Compiling GLib Applications on UNIX</title>
<para>
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
<application>pkg-config</application> utility.
</para>
<para>
The following interactive shell session demonstrates how
<application>pkg-config</application> is used (the actual output on
your system may be different):
<programlisting>
$ 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
</programlisting>
</para>
<para>
See the <ulink url="http://www.freedesktop.org/wiki/Software/pkg-config">pkg-config website</ulink>
for more information about <application>pkg-config</application>.
</para>
<para>
If your application uses or <structname>GObject</structname>
features, it must be compiled and linked with the options returned
by the following <application>pkg-config</application> invocation:
<programlisting>
$ pkg-config --cflags --libs gobject-2.0
</programlisting>
</para>
<para>
If your application uses modules, it must be compiled and linked
with the options returned by one of the following
<application>pkg-config</application> invocations:
<programlisting>
$ pkg-config --cflags --libs gmodule-no-export-2.0
$ pkg-config --cflags --libs gmodule-2.0
</programlisting>
The difference between the two is that gmodule-2.0 adds
<option>--export-dynamic</option> to the linker flags,
which is often not needed.
</para>
<para>
The simplest way to compile a program is to use the "backticks"
feature of the shell. If you enclose a command in backticks
(<emphasis>not single quotes</emphasis>), then its output will
be substituted into the command line before execution. So to
compile a GLib Hello, World, you would type the following:
<programlisting>
$ cc hello.c `pkg-config --cflags --libs glib-2.0` -o hello
</programlisting>
</para>
<note><para>
Note that the name of the file must come before the other options
(such as <emphasis>pkg-config</emphasis>), or else you may get an
error from the linker.
</para></note>
<para>
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 <literal>-DGLIB_DISABLE_DEPRECATION_WARNINGS</literal>
</para>
<para>
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.
</para>
<para>
Since GLib 2.62, the older deprecation mechanism of hiding deprecated interfaces
entirely from the compiler by using the preprocessor symbol
<literal>G_DISABLE_DEPRECATED</literal> has been removed. All deprecations
are now handled using the above mechanism.
</para>
<para>
The recommended way of using GLib has always been to only include the
toplevel headers <filename>glib.h</filename>,
<filename>glib-object.h</filename>, <filename>gio.h</filename>.
Starting with 2.32, GLib enforces this by generating an error
when individual headers are directly included.
</para>
<para>
Still, there are some exceptions; these headers have to be included
separately:
<filename>gmodule.h</filename>,
<filename>glib-unix.h</filename>,
<filename>glib/gi18n-lib.h</filename> or
<filename>glib/gi18n.h</filename> (see
the <link linkend="glib-I18N">Internationalization section</link>),
<filename>glib/gprintf.h</filename> and
<filename>glib/gstdio.h</filename>
(we don't want to pull in all of stdio).
</para>
</refsect1>
</refentry>
docs/reference/glib/cross.xml
+146
View File
@@ -0,0 +1,146 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-cross-compiling" revision="7 Aug 2018">
<refmeta>
<refentrytitle>Cross-compiling the GLib package</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Cross-compiling the GLib Package</refname>
<refpurpose>
How to cross-compile GLib
</refpurpose>
</refnamediv>
<refsect1 id="cross">
<title>Building the Library for a different architecture</title>
<para>
Cross-compilation is the process of compiling a program or
library on a different architecture or operating system then
it will be run upon. GLib is slightly more difficult to
cross-compile than many packages because much of GLib is
about hiding differences between different systems.
</para>
<para>
These notes cover things specific to cross-compiling GLib;
for general information about cross-compilation, see the
<ulink url="http://mesonbuild.com/Cross-compilation.html">meson</ulink>
info pages.
</para>
<para>
GLib tries to detect as much information as possible about
the target system by compiling and linking programs without
actually running anything; however, some information GLib
needs is not available this way. This information needs
to be provided to meson via a ‘cross file’.
</para>
<para>
As an example of using a cross file, to cross compile for
the ‘MingW32’ Win64 runtime environment on a Linux system,
create a file <filename>cross_file.txt</filename> with the following
contents:
</para>
<programlisting>
[host_machine]
system = 'windows'
cpu_family = 'x86_64'
cpu = 'x86_64'
endian = 'little'
[properties]
c_args = []
c_link_args = []
[binaries]
c = 'x86_64-w64-mingw32-gcc'
cpp = 'x86_64-w64-mingw32-g++'
ar = 'x86_64-w64-mingw32-ar'
objcopy = 'x86_64-w64-mingw32-objcopy'
strip = 'x86_64-w64-mingw32-strip'
pkgconfig = 'x86_64-w64-mingw32-pkg-config'
windres = 'x86_64-w64-mingw32-windres'
</programlisting>
<para>
Then execute the following commands:
</para>
<programlisting>
meson --cross-file cross_file.txt builddir
</programlisting>
<para>
The complete list of cross properties follows. Most
of these won't need to be set in most cases.
</para>
</refsect1>
<refsect1 id="cross-properties">
<title>Cross properties</title>
<formalpara>
<title>have_[function]</title>
<para>
When meson checks if a function is supported, the test can be
overridden by setting the
<literal>have_<replaceable>function</replaceable></literal> property
to <constant>true</constant> or <constant>false</constant>.
For example <programlisting>Checking for function "fsync" : YES</programlisting>
can be overridden by setting <programlisting>have_fsync = false</programlisting>
</para>
</formalpara>
<formalpara>
<title>growing_stack=[true/false]</title>
<para>
Whether the stack grows up or down. Most places will want
<constant>false</constant>.
A few architectures, such as PA-RISC need <constant>true</constant>.
</para>
</formalpara>
<formalpara>
<title>have_strlcpy=[true/false]</title>
<para>
Whether you have <function>strlcpy()</function> that matches
OpenBSD. Defaults to <constant>false</constant>, which is safe,
since GLib uses a built-in version in that case.
</para>
</formalpara>
<formalpara>
<title>va_val_copy=[true/false]</title>
<para>
Whether <type>va_list</type> can be copied as a pointer. If set
to <constant>false</constant>, then <function>memcopy()</function>
will be used. Only matters if you don't have
<function>va_copy()</function> or <function>__va_copy()</function>.
(So, doesn't matter for GCC.)
Defaults to <constant>true</constant> which is slightly more common
than <constant>false</constant>.
</para>
</formalpara>
<formalpara>
<title>have_c99_vsnprintf=[true/false]</title>
<para>
Whether you have a <function>vsnprintf()</function> with C99
semantics. (C99 semantics means returning the number of bytes
that would have been written had the output buffer had enough
space.) Defaults to <constant>false</constant>.
</para>
</formalpara>
<formalpara>
<title>have_c99_snprintf=[true/false]</title>
<para>
Whether you have a <function>snprintf()</function> with C99
semantics. (C99 semantics means returning the number of bytes
that would have been written had the output buffer had enough
space.) Defaults to <constant>false</constant>.
</para>
</formalpara>
</refsect1>
</refentry>
docs/reference/glib/file-name-encodings.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

docs/reference/glib/file-name-encodings.sxd
BIN
View File
Binary file not shown.
docs/reference/glib/glib-docs.xml
+282
View File
@@ -0,0 +1,282 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>GLib Reference Manual</title>
<releaseinfo>
for GLib &version;
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="https://developer.gnome.org/glib/unstable/">https://developer.gnome.org/glib/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<chapter id="glib">
<title>GLib Overview</title>
<para>
GLib is a general-purpose utility library, which provides many useful
data types, macros, type conversions, string utilities, file utilities,
a mainloop abstraction, and so on. It works on many UNIX-like platforms,
as well as Windows and OS X. GLib is released under the GNU Lesser
General Public License (GNU LGPL).
</para>
<xi:include href="building.xml" />
<xi:include href="cross.xml" />
<xi:include href="programming.xml" />
<xi:include href="xml/compiling.xml" />
<xi:include href="running.xml" />
<xi:include href="changes.xml" />
<xi:include href="resources.xml" />
</chapter>
<chapter id="glib-fundamentals">
<title>GLib Fundamentals</title>
<xi:include href="xml/version.xml" />
<xi:include href="xml/types.xml" />
<xi:include href="xml/macros.xml" />
<xi:include href="xml/type_conversion.xml" />
<xi:include href="xml/byte_order.xml" />
<xi:include href="xml/checkedmath.xml" />
<xi:include href="xml/numerical.xml" />
<xi:include href="xml/macros_misc.xml" />
<xi:include href="xml/atomic_operations.xml" />
</chapter>
<chapter id="glib-core">
<title>GLib Core Application Support</title>
<xi:include href="xml/main.xml" />
<xi:include href="xml/threads.xml" />
<xi:include href="xml/thread_pools.xml" />
<xi:include href="xml/async_queues.xml" />
<xi:include href="xml/modules.xml" />
<xi:include href="xml/memory.xml" />
<xi:include href="xml/memory_slices.xml" />
<xi:include href="xml/iochannels.xml" />
<xi:include href="xml/error_reporting.xml" />
<xi:include href="xml/warnings.xml" />
<xi:include href="xml/messages.xml" />
</chapter>
<chapter id="glib-utilities">
<title>GLib Utilities</title>
<xi:include href="xml/string_utils.xml" />
<xi:include href="xml/conversions.xml" />
<xi:include href="xml/unicode.xml" />
<xi:include href="xml/base64.xml" />
<xi:include href="xml/checksum.xml" />
<xi:include href="xml/hmac.xml" />
<xi:include href="xml/i18n.xml" />
<xi:include href="xml/date.xml" />
<xi:include href="xml/timezone.xml" />
<xi:include href="xml/date-time.xml" />
<xi:include href="xml/random_numbers.xml" />
<xi:include href="xml/hooks.xml" />
<xi:include href="xml/misc_utils.xml" />
<xi:include href="xml/scanner.xml" />
<xi:include href="xml/timers.xml" />
<xi:include href="xml/spawn.xml" />
<xi:include href="xml/fileutils.xml" />
<xi:include href="xml/gurifuncs.xml" />
<xi:include href="xml/ghostutils.xml" />
<xi:include href="xml/shell.xml" />
<xi:include href="xml/option.xml" />
<xi:include href="xml/patterns.xml" />
<xi:include href="xml/gregex.xml" />
<xi:include href="regex-syntax.xml" />
<xi:include href="xml/markup.xml" />
<xi:include href="xml/keyfile.xml" />
<xi:include href="xml/bookmarkfile.xml" />
<xi:include href="xml/testing.xml" />
<xi:include href="xml/gunix.xml" />
<xi:include href="xml/windows.xml" />
<xi:include href="xml/uuid.xml" />
</chapter>
<chapter id="glib-data-types">
<title>GLib Data Types</title>
<xi:include href="xml/linked_lists_double.xml" />
<xi:include href="xml/linked_lists_single.xml" />
<xi:include href="xml/queue.xml" />
<xi:include href="xml/sequence.xml" />
<xi:include href="xml/trash_stack.xml" />
<xi:include href="xml/hash_tables.xml" />
<xi:include href="xml/strings.xml" />
<xi:include href="xml/string_chunks.xml" />
<xi:include href="xml/arrays.xml" />
<xi:include href="xml/arrays_pointer.xml" />
<xi:include href="xml/arrays_byte.xml" />
<xi:include href="xml/trees-binary.xml" />
<xi:include href="xml/trees-nary.xml" />
<xi:include href="xml/quarks.xml" />
<xi:include href="xml/datalist.xml" />
<xi:include href="xml/datasets.xml" />
<xi:include href="xml/gvarianttype.xml"/>
<xi:include href="xml/gvariant.xml"/>
<xi:include href="gvariant-varargs.xml"/>
<xi:include href="gvariant-text.xml"/>
<xi:include href="xml/refcount.xml"/>
<xi:include href="xml/rcbox.xml"/>
<xi:include href="xml/arcbox.xml"/>
<xi:include href="xml/refstring.xml"/>
</chapter>
<chapter id="deprecated">
<title>Deprecated APIs</title>
<xi:include href="xml/threads-deprecated.xml"/>
<xi:include href="xml/caches.xml" />
<xi:include href="xml/relations.xml" />
<xi:include href="xml/completion.xml" />
</chapter>
<chapter id="tools">
<title>GLib Tools</title>
<xi:include href="glib-gettextize.xml" />
</chapter>
<chapter id="deprecated-tools">
<title>Deprecated Tools</title>
<xi:include href="gtester.xml" />
<xi:include href="gtester-report.xml" />
</chapter>
<index id="api-index-full">
<title>Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-deprecated" role="deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-2" role="2.2">
<title>Index of new symbols in 2.2</title>
<xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-4" role="2.4">
<title>Index of new symbols in 2.4</title>
<xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-6" role="2.6">
<title>Index of new symbols in 2.6</title>
<xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-8" role="2.8">
<title>Index of new symbols in 2.8</title>
<xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-10" role="2.10">
<title>Index of new symbols in 2.10</title>
<xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-12" role="2.12">
<title>Index of new symbols in 2.12</title>
<xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-14" role="2.14">
<title>Index of new symbols in 2.14</title>
<xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-16" role="2.16">
<title>Index of new symbols in 2.16</title>
<xi:include href="xml/api-index-2.16.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-18" role="2.18">
<title>Index of new symbols in 2.18</title>
<xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-20" role="2.20">
<title>Index of new symbols in 2.20</title>
<xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-22" role="2.22">
<title>Index of new symbols in 2.22</title>
<xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-24" role="2.24">
<title>Index of new symbols in 2.24</title>
<xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-26" role="2.26">
<title>Index of new symbols in 2.26</title>
<xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-28" role="2.28">
<title>Index of new symbols in 2.28</title>
<xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-30" role="2.30">
<title>Index of new symbols in 2.30</title>
<xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-32" role="2.32">
<title>Index of new symbols in 2.32</title>
<xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-34" role="2.34">
<title>Index of new symbols in 2.34</title>
<xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-36" role="2.36">
<title>Index of new symbols in 2.36</title>
<xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-38" role="2.38">
<title>Index of new symbols in 2.38</title>
<xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-40" role="2.40">
<title>Index of new symbols in 2.40</title>
<xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-42" role="2.42">
<title>Index of new symbols in 2.42</title>
<xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-44" role="2.44">
<title>Index of new symbols in 2.44</title>
<xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-46" role="2.46">
<title>Index of new symbols in 2.46</title>
<xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-48" role="2.48">
<title>Index of new symbols in 2.48</title>
<xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-50" role="2.50">
<title>Index of new symbols in 2.50</title>
<xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-52" role="2.52">
<title>Index of new symbols in 2.52</title>
<xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-54" role="2.54">
<title>Index of new symbols in 2.54</title>
<xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-56" role="2.56">
<title>Index of new symbols in 2.56</title>
<xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-58" role="2.58">
<title>Index of new symbols in 2.58</title>
<xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-60" role="2.60">
<title>Index of new symbols in 2.60</title>
<xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-62" role="2.62">
<title>Index of new symbols in 2.62</title>
<xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>
docs/reference/glib/glib-gettextize.xml
+88
View File
@@ -0,0 +1,88 @@
<refentry id="glib-gettextize" lang="en">
<refentryinfo>
<title>glib-gettextize</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Owen</firstname>
<surname>Taylor</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-gettextize</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-gettextize</refname>
<refpurpose>gettext internationalization utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-gettextize</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="opt">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-gettextize</command> helps to prepare a source package for being
internationalized through <application>gettext</application>.
It is a variant of the <command>gettextize</command> that ships with
<application>gettext</application>.
</para>
<para><command>glib-gettextize</command> differs
from <command>gettextize</command> in that it doesn't create an
<filename>intl/</filename> subdirectory and doesn't modify
<filename>po/ChangeLog</filename> (note that newer versions of
<command>gettextize</command> behave like this when called with the
<option>--no-changelog</option> option).
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>, <option>--copy</option></term>
<listitem><para>
copy files instead of making symlinks
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>
force writing of new files even if old ones exist
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry><refentrytitle>gettextize</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
docs/reference/glib/glib-overrides.txt
+294
View File
@@ -0,0 +1,294 @@
# This file makes most of the thread related macros look like
# functions, which they really were, if possible easy.
<MACRO>
<NAME>GLIB_DISABLE_DEPRECATION_WARNINGS</NAME>
#ifdef GLIB_DISABLE_DEPRECATION_WARNINGS
</MACRO>
<MACRO>
<NAME>G_ATOMIC_LOCK_FREE</NAME>
#define G_ATOMIC_LOCK_FREE
</MACRO>
# default thread implementation
<MACRO>
<NAME>G_THREADS_IMPL_POSIX</NAME>
#define G_THREADS_IMPL_POSIX
</MACRO>
<MACRO>
<NAME>G_THREADS_IMPL_WIN32</NAME>
#define G_THREADS_IMPL_NONE
</MACRO>
# threads supported?
<FUNCTION>
<NAME>g_thread_supported</NAME>
<RETURNS>gboolean</RETURNS>
</FUNCTION>
# GMutex
<FUNCTION>
<NAME>g_mutex_new</NAME>
<RETURNS>GMutex *</RETURNS>
</FUNCTION>
<FUNCTION>
<NAME>g_mutex_lock</NAME>
<RETURNS>void</RETURNS>
GMutex *mutex
</FUNCTION>
<FUNCTION>
<NAME>g_mutex_trylock</NAME>
<RETURNS>gboolean</RETURNS>
GMutex *mutex
</FUNCTION>
<FUNCTION>
<NAME>g_mutex_unlock</NAME>
<RETURNS>void</RETURNS>
GMutex *mutex
</FUNCTION>
<FUNCTION>
<NAME>g_mutex_free</NAME>
<RETURNS>void</RETURNS>
GMutex *mutex
</FUNCTION>
# GStaticMutex
<STRUCT>
<NAME>GStaticMutex</NAME>
</STRUCT>
<MACRO>
<NAME>G_STATIC_MUTEX_INIT</NAME>
#define G_STATIC_MUTEX_INIT
</MACRO>
<FUNCTION>
<NAME>g_static_mutex_lock</NAME>
<RETURNS>void</RETURNS>
GStaticMutex* mutex
</FUNCTION>
<FUNCTION>
<NAME>g_static_mutex_trylock</NAME>
<RETURNS>gboolean</RETURNS>
GStaticMutex* mutex
</FUNCTION>
<FUNCTION>
<NAME>g_static_mutex_unlock</NAME>
<RETURNS>void</RETURNS>
GStaticMutex* mutex
</FUNCTION>
<FUNCTION>
<NAME>g_static_mutex_get_mutex</NAME>
<RETURNS>GMutex *</RETURNS>
GStaticMutex* mutex
</FUNCTION>
# GThread
<FUNCTION>
<NAME>g_thread_yield</NAME>
<RETURNS>void</RETURNS>
</FUNCTION>
<FUNCTION>
<NAME>g_thread_create</NAME>
<RETURNS>GThread *</RETURNS>
GThreadFunc func
gpointer data,
gboolean joinable,
GError **error
</FUNCTION>
# G_LOCK_* macros
<MACRO>
<NAME>G_LOCK_DEFINE</NAME>
#define G_LOCK_DEFINE(name)
</MACRO>
<MACRO>
<NAME>G_LOCK_DEFINE_STATIC</NAME>
#define G_LOCK_DEFINE_STATIC(name)
</MACRO>
<MACRO>
<NAME>G_LOCK_EXTERN</NAME>
#define G_LOCK_EXTERN(name)
</MACRO>
<MACRO>
<NAME>G_LOCK</NAME>
#define G_LOCK(name)
</MACRO>
<MACRO>
<NAME>G_UNLOCK</NAME>
#define G_UNLOCK(name)
</MACRO>
<MACRO>
<NAME>G_TRYLOCK</NAME>
#define G_TRYLOCK(name)
</MACRO>
# GCond
<FUNCTION>
<NAME>g_cond_new</NAME>
<RETURNS>GCond*</RETURNS>
</FUNCTION>
<FUNCTION>
<NAME>g_cond_signal</NAME>
<RETURNS>void</RETURNS>
GCond *cond
</FUNCTION>
<FUNCTION>
<NAME>g_cond_broadcast</NAME>
<RETURNS>void</RETURNS>
GCond *cond
</FUNCTION>
<FUNCTION>
<NAME>g_cond_wait</NAME>
<RETURNS>void</RETURNS>
GCond *cond, GMutex *mutex
</FUNCTION>
<FUNCTION>
<NAME>g_cond_timed_wait</NAME>
<RETURNS>gboolean</RETURNS>
GCond *cond, GMutex *mutex, GTimeVal *abs_time
</FUNCTION>
<FUNCTION>
<NAME>g_cond_free</NAME>
<RETURNS>void</RETURNS>
GCond *cond
</FUNCTION>
# GPrivate
<MACRO>
<NAME>G_PRIVATE_INIT</NAME>
#define G_PRIVATE_INIT(notify)
</MACRO>
# GStaticPrivate
<MACRO>
<NAME>G_STATIC_PRIVATE_INIT</NAME>
#define G_STATIC_PRIVATE_INIT
</MACRO>
# Definitions for different operating systems
<MACRO>
<NAME>G_OS_UNIX</NAME>
#define G_OS_UNIX
</MACRO>
<MACRO>
<NAME>G_OS_WIN32</NAME>
#define G_OS_WIN32
</MACRO>
# g_ascii_isxxx
<FUNCTION>
<NAME>g_ascii_isalnum</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isalpha</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_iscntrl</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isdigit</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isgraph</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_islower</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isprint</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_ispunct</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isspace</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isupper</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isxdigit</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
# g_atomic
<FUNCTION>
<NAME>g_atomic_int_inc</NAME>
<RETURNS>void</RETURNS>
gint *atomic
</FUNCTION>
<FUNCTION>
<NAME>g_atomic_int_dec_and_test</NAME>
<RETURNS>gboolean</RETURNS>
gint *atomic
</FUNCTION>
<MACRO>
<NAME>G_VA_COPY</NAME>
#define G_VA_COPY(ap1,ap2)
</MACRO>
docs/reference/glib/glib-sections.txt
+3753
View File
File diff suppressed because it is too large Load Diff
docs/reference/glib/gtester-report.xml
+78
View File
@@ -0,0 +1,78 @@
<refentry id="gtester-report">
<refentryinfo>
<title>gtester-report</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Tim</firstname>
<surname>Janik</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtester-report</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtester-report</refname>
<refpurpose>test report formatting utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtester-report</command>
<arg choice="opt" rep="repeat">option</arg>
<arg>gtester-log</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gtester-report</command> is a script which converts
the XML output generated by gtester into HTML.
</para>
<para>Since GLib 2.62, <command>gtester-report</command> is deprecated. Use
TAP for reporting test results instead, and feed it to the test harness provided
by your build system.</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--subunit</option></term>
<listitem><para>
Output subunit. Needs python-subunit.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>gtester</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
docs/reference/glib/gtester.xml
+192
View File
@@ -0,0 +1,192 @@
<refentry id="gtester">
<refentryinfo>
<title>gtester</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Tim</firstname>
<surname>Janik</surname>
</author>
<author>
<contrib>Developer</contrib>
<firstname>Sven</firstname>
<surname>Herzberg</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtester</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtester</refname>
<refpurpose>test running utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtester</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg>testprogram</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gtester</command> is a utility to run unit tests that have
been written using the GLib test framework.
</para>
<para>Since GLib 2.62, <command>gtester-report</command> is deprecated. Use
TAP for reporting test results instead, and feed it to the test harness provided
by your build system.</para>
<para>
When called with the <option>-o</option> option, <command>gtester</command>
writes an XML report of the test results, which can be converted
into HTML using the <command>gtester-report</command> utility.
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--g-fatal-warnings</option></term>
<listitem><para>
make warnings fatal
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-k</option>, <option>--keep-going</option></term>
<listitem><para>
continue running after tests failed
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option></term>
<listitem><para>
list paths of available test cases
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-m=<replaceable>MODE</replaceable></option></term>
<listitem><para>
run test cases in <replaceable>MODE</replaceable>, which can be one of:
<variablelist>
<varlistentry>
<term><option>perf</option></term>
<listitem><para>
run performance tests
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>slow</option>, <option>thorough</option></term>
<listitem><para>
run slow tests, or repeat non-deterministic tests more often
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>quick</option></term>
<listitem><para>
do not run slow or performance tests, or do extra repeats
of non-deterministic tests (default)
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>undefined</option></term>
<listitem><para>
run test cases that deliberately provoke checks or assertion
failures, if implemented (default)
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>no-undefined</option></term>
<listitem><para>
do not run test cases that deliberately provoke checks or
assertion failures
</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p=<replaceable>TESTPATH</replaceable></option></term>
<listitem><para>
only run test cases matching <replaceable>TESTPATH</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s=<replaceable>TESTPATH</replaceable></option></term>
<listitem><para>
skip test cases matching <replaceable>TESTPATH</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--seed=<replaceable>SEEDSTRING</replaceable></option></term>
<listitem><para>
run all test cases with random number seed <replaceable>SEEDSTRING</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-o=<replaceable>LOGFILE</replaceable></option></term>
<listitem><para>
write the test log to <replaceable>LOGFILE</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-q</option>, <option>--quiet</option></term>
<listitem><para>
suppress per test binary output
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose</option></term>
<listitem><para>
report success per testcase
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>gtester-report</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
docs/reference/glib/gvariant-text.xml
+622
View File
@@ -0,0 +1,622 @@
<?xml version='1.0' encoding='utf-8'?>
<refentry id='gvariant-text'>
<refmeta>
<refentrytitle>GVariant Text Format</refentrytitle>
</refmeta>
<refnamediv>
<refname>GVariant Text Format</refname>
<refpurpose>textual representation of GVariants</refpurpose>
</refnamediv>
<refsect1>
<title>GVariant Text Format</title>
<para>
This page attempts to document the GVariant text format as produced by
<link linkend='g-variant-print'><function>g_variant_print()</function></link> and parsed by the
<link linkend='g-variant-parse'><function>g_variant_parse()</function></link> family of functions. In most
cases the style closely resembles the formatting of literals in Python but there are some additions and
exceptions.
</para>
<para>
The functions that deal with GVariant text format absolutely always deal in utf-8. Conceptually, GVariant
text format is a string of Unicode characters -- not bytes. Non-ASCII but otherwise printable Unicode
characters are not treated any differently from normal ASCII characters.
</para>
<para>
The parser makes two passes. The purpose of the first pass is to determine the type of the value being
parsed. The second pass does the actual parsing. Based on the fact that all elements in an array have to
have the same type, GVariant is able to make some deductions that would not otherwise be possible. As an
example:
<informalexample><programlisting>[[1, 2, 3], [4, 5, 6]]</programlisting></informalexample>
is parsed as an array of arrays of integers (type '<literal>aai</literal>'), but
<informalexample><programlisting>[[1, 2, 3], [4, 5, 6.0]]</programlisting></informalexample>
is parsed as an array of arrays of doubles (type '<literal>aad</literal>').
</para>
<para>
As another example, GVariant is able to determine that
<informalexample><programlisting>["hello", nothing]</programlisting></informalexample>
is an array of maybe strings (type '<literal>ams</literal>').
</para>
<para>
What the parser accepts as valid input is dependent on context. The API permits for out-of-band type
information to be supplied to the parser (which will change its behaviour). This can be seen in the
GSettings and GDBus command line utilities where the type information is available from the schema or the
remote introspection information. The additional information can cause parses to succeed when they would not
otherwise have been able to (by resolving ambiguous type information) or can cause them to fail (due to
conflicting type information). Unless stated otherwise, the examples given in this section assume that no
out-of-band type data has been given to the parser.
</para>
</refsect1>
<refsect1>
<title>Syntax Summary</title>
<para>
The following table describes the rough meaning of symbols that may appear inside GVariant text format.
Each symbol is described in detail in its own section, including usage examples.
</para>
<informaltable>
<tgroup cols='2'>
<colspec colname='col_0'/>
<colspec colname='col_1'/>
<tbody>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'>Symbol</emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'>Meaning</emphasis>
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>true</literal></emphasis>,
<emphasis role='strong'><literal>false</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-booleans'>Booleans</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>""</literal></emphasis>,
<emphasis role='strong'><literal>''</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
String literal. See <link linkend='gvariant-text-strings'>Strings</link> below.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
numbers
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
See <link linkend='gvariant-text-numbers'>Numbers</link> below.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>()</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-tuples'>Tuples</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>[]</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-arrays'>Arrays</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>{}</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-dictionaries'>Dictionaries and Dictionary Entries</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>&lt;&gt;</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-variants'>Variants</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>just</literal></emphasis>,
<emphasis role='strong'><literal>nothing</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-maybe-types'>Maybe Types</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>@</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-type-annotations'>Type Annotations</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
type keywords
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<literal>boolean</literal>,
<literal>byte</literal>,
<literal>int16</literal>,
<literal>uint16</literal>,
<literal>int32</literal>,
<literal>uint32</literal>,
<literal>handle</literal>,
<literal>int64</literal>,
<literal>uint64</literal>,
<literal>double</literal>,
<literal>string</literal>,
<literal>objectpath</literal>,
<literal>signature</literal>
</para>
<para>
See <link linkend='gvariant-text-type-annotations'>Type Annotations</link> below.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>b""</literal></emphasis>,
<emphasis role='strong'><literal>b''</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-bytestrings'>Bytestrings</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>%</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-positional'>Positional Parameters</link>.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<refsect2 id='gvariant-text-booleans'>
<title>Booleans</title>
<para>
The strings <literal>true</literal> and <literal>false</literal> are parsed as booleans. This is the only
way to specify a boolean value.
</para>
</refsect2>
<refsect2 id='gvariant-text-strings'>
<title>Strings</title>
<para>
Strings literals must be quoted using <literal>""</literal> or <literal>''</literal>. The two are
completely equivalent (except for the fact that each one is unable to contain itself unescaped).
</para>
<para>
Strings are Unicode strings with no particular encoding. For example, to specify the character
<literal>é</literal>, you just write <literal>'é'</literal>. You could also give the Unicode codepoint of
that character (U+E9) as the escape sequence <literal>'\u00e9'</literal>. Since the strings are pure
Unicode, you should not attempt to encode the utf-8 byte sequence corresponding to the string using escapes;
it won't work and you'll end up with the individual characters corresponding to each byte.
</para>
<para>
Unicode escapes of the form <literal>\uxxxx</literal> and <literal>\Uxxxxxxxx</literal> are supported, in
hexidecimal. The usual control sequence escapes <literal>\a</literal>, <literal>\b</literal>,
<literal>\f</literal>, <literal>\n</literal>, <literal>\r</literal>, <literal>\t</literal> and
<literal>\v</literal> are supported. Additionally, a <literal>\</literal> before a newline character causes
the newline to be ignored. Finally, any other character following <literal>\</literal> is copied literally
(for example, <literal>\"</literal> or <literal>\\</literal>) but for forwards compatibility with future
additions you should only use this feature when necessary for escaping backslashes or quotes.
</para>
<para>
The usual octal and hexidecimal escapes <literal>\0nnn</literal> and <literal>\xnn</literal> are not
supported here. Those escapes are used to encode byte values and GVariant strings are Unicode.
</para>
<para>
Single-character strings are not interpreted as bytes. Bytes must be specified by their numerical value.
</para>
</refsect2>
<refsect2 id='gvariant-text-numbers'>
<title>Numbers</title>
<para>
Numbers are given by default as decimal values. Octal and hex values can be given in the usual way (by
prefixing with <literal>0</literal> or <literal>0x</literal>). Note that GVariant considers bytes to be
unsigned integers and will print them as a two digit hexidecimal number by default.
</para>
<para>
Floating point numbers can also be given in the usual ways, including scientific and hexidecimal notations.
</para>
<para>
For lack of additional information, integers will be parsed as int32 values by default. If the number has a
point or an 'e' in it, then it will be parsed as a double precision floating point number by default. If
type information is available (either explicitly or inferred) then that type will be used instead.
</para>
<para>
Some examples:
</para>
<para>
<literal>5</literal> parses as the int32 value five.
</para>
<para>
<literal>37.5</literal> parses as a floating point value.
</para>
<para>
<literal>3.75e1</literal> parses the same as the value above.
</para>
<para>
<literal>uint64 7</literal> parses seven as a uint64.
See <link linkend='gvariant-text-type-annotations'>Type Annotations</link>.
</para>
</refsect2>
<refsect2 id='gvariant-text-tuples'>
<title>Tuples</title>
<para>
Tuples are formed using the same syntax as Python. Here are some examples:
</para>
<para>
<literal>()</literal> parses as the empty tuple.
</para>
<para>
<literal>(5,)</literal> is a tuple containing a single value.
</para>
<para>
<literal>("hello", 42)</literal> is a pair. Note that values of different types are permitted.
</para>
</refsect2>
<refsect2 id='gvariant-text-arrays'>
<title>Arrays</title>
<para>
Arrays are formed using the same syntax as Python uses for lists (which is arguably the term that GVariant
should have used). Note that, unlike Python lists, GVariant arrays are statically typed. This has two
implications.
</para>
<para>
First, all items in the array must have the same type. Second, the type of the array must be known, even in
the case that it is empty. This means that (unless there is some other way to infer it) type information
will need to be given explicitly for empty arrays.
</para>
<para>
The parser is able to infer some types based on the fact that all items in an array must have the same type.
See the examples below:
</para>
<para>
<literal>[1]</literal> parses (without additional type information) as a one-item array of signed integers.
</para>
<para>
<literal>[1, 2, 3]</literal> parses (similarly) as a three-item array.
</para>
<para>
<literal>[1, 2, 3.0]</literal> parses as an array of doubles. This is the most simple case of the type
inferencing in action.
</para>
<para>
<literal>[(1, 2), (3, 4.0)]</literal> causes the 2 to also be parsed as a double (but the 1 and 3 are still
integers).
</para>
<para>
<literal>["", nothing]</literal> parses as an array of maybe strings. The presence of
"<literal>nothing</literal>" clearly implies that the array elements are nullable.
</para>
<para>
<literal>[[], [""]]</literal> will parse properly because the type of the first (empty) array can be
inferred to be equal to the type of the second array (both are arrays of strings).
</para>
<para>
<literal>[b'hello', []]</literal> looks odd but will parse properly.
See <link linkend='gvariant-text-bytestrings'>Bytestrings</link>
</para>
<para>
And some examples of errors:
</para>
<para>
<literal>["hello", 42]</literal> fails to parse due to conflicting types.
</para>
<para>
<literal>[]</literal> will fail to parse without additional type information.
</para>
</refsect2>
<refsect2 id='gvariant-text-dictionaries'>
<title>Dictionaries and Dictionary Entries</title>
<para>
Dictionaries and dictionary entries are both specified using the <literal>{}</literal> characters.
</para>
<para>
The dictionary syntax is more commonly used. This is what the printer elects to use in the normal case of
dictionary entries appearing in an array (aka "a dictionary"). The separate syntax for dictionary entries
is typically only used for when the entries appear on their own, outside of an array (which is valid but
unusual). Of course, you are free to use the dictionary entry syntax within arrays but there is no good
reason to do so (and the printer itself will never do so). Note that, as with arrays, the type of empty
dictionaries must be established (either explicitly or through inference).
</para>
<para>
The dictionary syntax is the same as Python's syntax for dictionaries. Some examples:
</para>
<para>
<literal>@a{sv} {}</literal> parses as the empty dictionary of everyone's favourite type.
</para>
<para>
<literal>@a{sv} []</literal> is the same as above (owing to the fact that dictionaries are really arrays).
</para>
<para>
<literal>{1: "one", 2: "two", 3: "three"}</literal> parses as a dictionary mapping integers to strings.
</para>
<para>
The dictionary entry syntax looks just like a pair (2-tuple) that uses braces instead of parens. The
presence of a comma immediately following the key differentiates it from the dictionary syntax (which
features a colon after the first key). Some examples:
</para>
<para>
<literal>{1, "one"}</literal> is a free-standing dictionary entry that can be parsed on its own or as part
of another container value.
</para>
<para>
<literal>[{1, "one"}, {2, "two"}, {3, "three"}]</literal> is exactly equivalent to the dictionary example
given above.
</para>
</refsect2>
<refsect2 id='gvariant-text-variants'>
<title>Variants</title>
<para>
Variants are denoted using angle brackets (aka "XML brackets"), <literal>&lt;&gt;</literal>. They may not
be omitted.
</para>
<para>
Using <literal>&lt;&gt;</literal> effectively disrupts the type inferencing that occurs between array
elements. This can have positive and negative effects.
</para>
<para>
<literal>[&lt;"hello"&gt;, &lt;42&gt;]</literal> will parse whereas <literal>["hello", 42]</literal> would
not.
</para>
<para>
<literal>[&lt;['']&gt;, &lt;[]&gt;]</literal> will fail to parse even though <literal>[[''], []]</literal>
parses successfully. You would need to specify <literal>[&lt;['']&gt;, &lt;@as []&gt;]</literal>.
</para>
<para>
<literal>{"title": &lt;"frobit"&gt;, "enabled": &lt;true&gt;, "width": &lt;800&gt;}</literal> is an example of
perhaps the most pervasive use of both dictionaries and variants.
</para>
</refsect2>
<refsect2 id='gvariant-text-maybe-types'>
<title>Maybe Types</title>
<para>
The syntax for specifying maybe types is inspired by Haskell.
</para>
<para>
The null case is specified using the keyword <literal>nothing</literal> and the non-null case is explicitly
specified using the keyword <literal>just</literal>. GVariant allows <literal>just</literal> to be omitted
in every case that it is able to unambiguously determine the intention of the writer. There are two cases
where it must be specified:
</para>
<itemizedlist>
<listitem>
<para>when using nested maybes, in order to specify the <literal>just nothing</literal> case</para>
</listitem>
<listitem>
<para>
to establish the nullability of the type of a value without explicitly specifying its full type
</para>
</listitem>
</itemizedlist>
<para>
Some examples:
</para>
<para>
<literal>just 'hello'</literal> parses as a non-null nullable string.
</para>
<para>
<literal>@ms 'hello'</literal> is the same (demonstrating how <literal>just</literal> can be dropped if the type is already
known).
</para>
<para>
<literal>nothing</literal> will not parse wtihout extra type information.
</para>
<para>
<literal>@ms nothing</literal> parses as a null nullable string.
</para>
<para>
<literal>[just 3, nothing]</literal> is an array of nullable integers
</para>
<para>
<literal>[3, nothing]</literal> is the same as the above (demonstrating another place were
<literal>just</literal> can be dropped).
</para>
<para>
<literal>[3, just nothing]</literal> parses as an array of maybe maybe integers (type
<literal>'ammi'</literal>).
</para>
</refsect2>
<refsect2 id='gvariant-text-type-annotations'>
<title>Type Annotations</title>
<para>
Type annotations allow additional type information to be given to the parser. Depending on the context,
this type information can change the output of the parser, cause an error when parsing would otherwise have
succeeded or resolve an error when parsing would have otherwise failed.
</para>
<para>
Type annotations come in two forms: type codes and type keywords.
</para>
<para>
Type keywords can be seen as more verbose (and more legible) versions of a common subset of the type codes.
The type keywords <literal>boolean</literal>, <literal>byte</literal>, <literal>int16</literal>,
<literal>uint16</literal>, <literal>int32</literal>, <literal>uint32</literal>, <literal>handle</literal>,
<literal>int64</literal>, <literal>uint64</literal>, <literal>double</literal>, <literal>string</literal>,
<literal>objectpath</literal> and literal <literal>signature</literal> are each exactly equivalent to their
corresponding type code.
</para>
<para>
Type codes are an <literal>@</literal> ("at" sign) followed by a definite GVariant type string. Some
examples:
</para>
<para>
<literal>uint32 5</literal> causes the number to be parsed unsigned instead of signed (the default).
</para>
<para>
<literal>@u 5</literal> is the same
</para>
<para>
<literal>objectpath "/org/gnome/xyz"</literal> creates an object path instead of a normal string
</para>
<para>
<literal>@au []</literal> specifies the type of the empty array (which would not parse otherwise)
</para>
<para>
<literal>@ms ""</literal> indicates that a string value is meant to have a maybe type
</para>
</refsect2>
<refsect2 id='gvariant-text-bytestrings'>
<title>Bytestrings</title>
<para>
The bytestring syntax is a piece of syntactic sugar meant to complement the bytestring APIs in GVariant. It
constructs arrays of non-nul bytes (type '<literal>ay</literal>') with a nul terminator at the end. These are
normal C strings with no particular encoding enforced, so the bytes may not be valid UTF-8.
Bytestrings are a special case of byte arrays; byte arrays (also type '<literal>ay</literal>'), in the general
case, can contain nul at any position, and need not end with nul.
</para>
<para>
Bytestrings are specified with either <literal>b""</literal> or <literal>b''</literal>. As with strings,
there is no fundamental difference between the two different types of quotes.
</para>
<para>
Bytestrings support the full range of escapes that you would expect (ie: those supported by
<link linkend='g-strcompress'><function>g_strcompress()</function></link>. This includes the normal control
sequence escapes (as mentioned in the section on strings) as well as octal and hexidecimal escapes of the
forms <literal>\0nnn</literal> and <literal>\xnn</literal>.
</para>
<para>
<literal>b'abc'</literal> is equivalent to <literal>[byte 0x61, 0x62, 0x63, 0]</literal>.
</para>
<para>
When formatting arrays of bytes, the printer will choose to display the array as a bytestring if it contains
a nul character at the end and no other nul bytes within. Otherwise, it is formatted as a normal array.
</para>
</refsect2>
<refsect2 id='gvariant-text-positional'>
<title>Positional Parameters</title>
<para>
Positional parameters are not a part of the normal GVariant text format, but they are mentioned here because
they can be used with <link linkend='g-variant-new-parsed'><function>g_variant_new_parsed()</function></link>.
</para>
<para>
A positional parameter is indicated with a <literal>%</literal> followed by any valid
<link linkend='gvariant-format-strings'>GVariant Format String</link>. Variable arguments are collected as
specified by the format string and the resulting value is inserted at the current position.
</para>
<para>
This feature is best explained by example:
</para>
<informalexample><programlisting><![CDATA[char *t = "xyz";
gboolean en = false;
GVariant *value;
value = g_variant_new_parsed ("{'title': <%s>, 'enabled': <%b>}", t, en);]]></programlisting></informalexample>
<para>
This constructs a dictionary mapping strings to variants (type '<literal>a{sv}</literal>') with two items in
it. The key names are parsed from the string and the values for those keys are taken as variable arguments
parameters.
</para>
<para>
The arguments are always collected in the order that they appear in the string to be parsed. Format strings
that collect multiple arguments are permitted, so you may require more varargs parameters than the number of
<literal>%</literal> signs that appear. You can also give format strings that collect no arguments, but
there's no good reason to do so.
</para>
</refsect2>
</refsect1>
</refentry>
docs/reference/glib/gvariant-varargs.xml
+1172
View File
File diff suppressed because it is too large Load Diff
docs/reference/glib/mainloop-states.eps
+306
View File
@@ -0,0 +1,306 @@
%!PS-Adobe-2.0 EPSF-2.0
%%Title: mainloop-stages.eps
%%Creator: fig2dev Version 3.2 Patchlevel 3c
%%CreationDate: Wed Nov 29 12:23:52 2000
%%For: otaylor@fresnel.labs.redhat.com (Owen Taylor)
%%BoundingBox: 0 0 503 291
%%Magnification: 1.0000
%%EndComments
/$F2psDict 200 dict def
$F2psDict begin
$F2psDict /mtrx matrix put
/col-1 {0 setgray} bind def
/col0 {0.000 0.000 0.000 srgb} bind def
/col1 {0.000 0.000 1.000 srgb} bind def
/col2 {0.000 1.000 0.000 srgb} bind def
/col3 {0.000 1.000 1.000 srgb} bind def
/col4 {1.000 0.000 0.000 srgb} bind def
/col5 {1.000 0.000 1.000 srgb} bind def
/col6 {1.000 1.000 0.000 srgb} bind def
/col7 {1.000 1.000 1.000 srgb} bind def
/col8 {0.000 0.000 0.560 srgb} bind def
/col9 {0.000 0.000 0.690 srgb} bind def
/col10 {0.000 0.000 0.820 srgb} bind def
/col11 {0.530 0.810 1.000 srgb} bind def
/col12 {0.000 0.560 0.000 srgb} bind def
/col13 {0.000 0.690 0.000 srgb} bind def
/col14 {0.000 0.820 0.000 srgb} bind def
/col15 {0.000 0.560 0.560 srgb} bind def
/col16 {0.000 0.690 0.690 srgb} bind def
/col17 {0.000 0.820 0.820 srgb} bind def
/col18 {0.560 0.000 0.000 srgb} bind def
/col19 {0.690 0.000 0.000 srgb} bind def
/col20 {0.820 0.000 0.000 srgb} bind def
/col21 {0.560 0.000 0.560 srgb} bind def
/col22 {0.690 0.000 0.690 srgb} bind def
/col23 {0.820 0.000 0.820 srgb} bind def
/col24 {0.500 0.190 0.000 srgb} bind def
/col25 {0.630 0.250 0.000 srgb} bind def
/col26 {0.750 0.380 0.000 srgb} bind def
/col27 {1.000 0.500 0.500 srgb} bind def
/col28 {1.000 0.630 0.630 srgb} bind def
/col29 {1.000 0.750 0.750 srgb} bind def
/col30 {1.000 0.880 0.880 srgb} bind def
/col31 {1.000 0.840 0.000 srgb} bind def
end
save
newpath 0 291 moveto 0 0 lineto 503 0 lineto 503 291 lineto closepath clip newpath
-106.0 402.0 translate
1 -1 scale
/cp {closepath} bind def
/ef {eofill} bind def
/gr {grestore} bind def
/gs {gsave} bind def
/sa {save} bind def
/rs {restore} bind def
/l {lineto} bind def
/m {moveto} bind def
/rm {rmoveto} bind def
/n {newpath} bind def
/s {stroke} bind def
/sh {show} bind def
/slc {setlinecap} bind def
/slj {setlinejoin} bind def
/slw {setlinewidth} bind def
/srgb {setrgbcolor} bind def
/rot {rotate} bind def
/sc {scale} bind def
/sd {setdash} bind def
/ff {findfont} bind def
/sf {setfont} bind def
/scf {scalefont} bind def
/sw {stringwidth} bind def
/tr {translate} bind def
/tnt {dup dup currentrgbcolor
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
bind def
/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
4 -2 roll mul srgb} bind def
/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
/$F2psEnd {$F2psEnteredState restore end} def
$F2psBegin
%%Page: 1 1
10 setmiterlimit
0.06000 0.06000 sc
%
% Fig objects follow
%
/Times-Roman ff 270.00 scf sf
9300 6225 m
gs 1 -1 sc (Initial[n+1]) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
9300 6540 m
gs 1 -1 sc (\(Recursion\)) dup sw pop 2 div neg 0 rm col0 sh gr
% Polyline
15.000 slw
[60] 0 sd
n 1905 6000 m 1800 6000 1800 6420 105 arcto 4 {pop} repeat
1800 6525 3120 6525 105 arcto 4 {pop} repeat
3225 6525 3225 6105 105 arcto 4 {pop} repeat
3225 6000 1905 6000 105 arcto 4 {pop} repeat
cp gs col0 s gr [] 0 sd
% Polyline
[60] 0 sd
gs clippath
3865 5498 m 3806 5431 l 3688 5535 l 3808 5490 l 3747 5602 l cp
3184 5976 m 3243 6043 l 3361 5939 l 3242 5985 l 3302 5872 l cp
eoclip
n 3225 6000 m
3825 5475 l gs col0 s gr gr
[] 0 sd
% arrowhead
n 3302 5872 m 3242 5985 l 3361 5939 l 3302 5872 l cp gs 0.00 setgray ef gr col0 s
% arrowhead
n 3747 5602 m 3808 5490 l 3688 5535 l 3747 5602 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 4980 5775 m 4875 5775 4875 6270 105 arcto 4 {pop} repeat
4875 6375 6870 6375 105 arcto 4 {pop} repeat
6975 6375 6975 5880 105 arcto 4 {pop} repeat
6975 5775 4980 5775 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
[60] 0 sd
gs clippath
8457 5969 m 8515 5900 l 8394 5799 l 8458 5911 l 8337 5868 l cp
8042 5505 m 7984 5574 l 8105 5675 l 8042 5564 l 8162 5606 l cp
eoclip
n 8025 5550 m
8475 5925 l gs col0 s gr gr
[] 0 sd
% arrowhead
n 8162 5606 m 8042 5564 l 8105 5675 l 8162 5606 l cp gs 0.00 setgray ef gr col0 s
% arrowhead
n 8337 5868 m 8458 5911 l 8394 5799 l 8337 5868 l cp gs 0.00 setgray ef gr col0 s
% Polyline
[60] 0 sd
n 8580 5850 m 8475 5850 8475 6570 105 arcto 4 {pop} repeat
8475 6675 10020 6675 105 arcto 4 {pop} repeat
10125 6675 10125 5955 105 arcto 4 {pop} repeat
10125 5850 8580 5850 105 arcto 4 {pop} repeat
cp gs col0 s gr [] 0 sd
% Polyline
n 7155 3825 m 7050 3825 7050 4320 105 arcto 4 {pop} repeat
7050 4425 9045 4425 105 arcto 4 {pop} repeat
9150 4425 9150 3930 105 arcto 4 {pop} repeat
9150 3825 7155 3825 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
n 5055 2100 m 4950 2100 4950 2595 105 arcto 4 {pop} repeat
4950 2700 6945 2700 105 arcto 4 {pop} repeat
7050 2700 7050 2205 105 arcto 4 {pop} repeat
7050 2100 5055 2100 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
n 2730 3900 m 2625 3900 2625 4395 105 arcto 4 {pop} repeat
2625 4500 4620 4500 105 arcto 4 {pop} repeat
4725 4500 4725 4005 105 arcto 4 {pop} repeat
4725 3900 2730 3900 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
[60] 0 sd
n 8580 1875 m 8475 1875 8475 2295 105 arcto 4 {pop} repeat
8475 2400 9645 2400 105 arcto 4 {pop} repeat
9750 2400 9750 1980 105 arcto 4 {pop} repeat
9750 1875 8580 1875 105 arcto 4 {pop} repeat
cp gs col0 s gr [] 0 sd
% Polyline
[60] 0 sd
gs clippath
8518 2419 m 8451 2358 l 8345 2474 l 8460 2416 l 8412 2534 l cp
8003 2848 m 8070 2909 l 8176 2793 l 8062 2852 l 8109 2733 l cp
eoclip
n 8047 2868 m
8475 2400 l gs col0 s gr gr
[] 0 sd
% arrowhead
n 8109 2733 m 8062 2852 l 8176 2793 l 8109 2733 l cp gs 0.00 setgray ef gr col0 s
% arrowhead
n 8412 2534 m 8460 2416 l 8345 2474 l 8412 2534 l cp gs 0.00 setgray ef gr col0 s
% Polyline
2 slj
gs clippath
3340 4475 m 3252 4494 l 3286 4648 l 3305 4522 l 3374 4629 l cp
eoclip
n 4875 6075 m 4874 6075 l 4872 6074 l 4868 6073 l 4861 6072 l 4852 6070 l
4839 6067 l 4824 6064 l 4805 6059 l 4783 6054 l 4759 6048 l
4731 6041 l 4701 6033 l 4669 6025 l 4635 6015 l 4600 6004 l
4563 5993 l 4526 5981 l 4487 5967 l 4448 5953 l 4408 5937 l
4367 5920 l 4326 5901 l 4284 5881 l 4241 5859 l 4198 5835 l
4154 5809 l 4109 5781 l 4063 5749 l 4016 5715 l 3968 5678 l
3920 5638 l 3872 5595 l 3825 5550 l 3780 5503 l 3737 5455 l
3697 5407 l 3660 5359 l 3626 5312 l 3594 5266 l 3566 5221 l
3540 5177 l 3516 5134 l 3494 5091 l 3474 5049 l 3455 5008 l
3438 4967 l 3422 4927 l 3408 4888 l 3394 4849 l 3382 4812 l
3371 4775 l 3360 4740 l 3350 4706 l 3342 4674 l 3334 4644 l
3327 4616 l 3321 4592 l 3316 4570 l 3311 4551 l 3308 4536 l
3305 4523 l 3303 4514 l
3300 4500 l gs col0 s gr gr
% arrowhead
0 slj
n 3374 4629 m 3305 4522 l 3286 4648 l 3374 4629 l cp gs 0.00 setgray ef gr col0 s
% Polyline
2 slj
gs clippath
6943 6114 m 6978 6197 l 7123 6135 l 6995 6141 l 7087 6052 l cp
eoclip
n 8475 4500 m 8475 4501 l 8475 4503 l 8475 4508 l 8475 4515 l 8474 4525 l
8474 4538 l 8473 4553 l 8472 4573 l 8470 4594 l 8468 4619 l
8465 4646 l 8462 4675 l 8457 4706 l 8452 4739 l 8445 4773 l
8437 4808 l 8427 4845 l 8416 4882 l 8403 4921 l 8388 4961 l
8370 5002 l 8350 5045 l 8326 5090 l 8299 5137 l 8268 5186 l
8232 5237 l 8192 5290 l 8148 5345 l 8100 5400 l 8057 5445 l
8013 5490 l 7968 5533 l 7923 5573 l 7878 5612 l 7833 5649 l
7789 5684 l 7745 5717 l 7701 5749 l 7658 5779 l 7615 5807 l
7573 5834 l 7531 5861 l 7489 5886 l 7447 5910 l 7407 5933 l
7366 5955 l 7327 5977 l 7288 5997 l 7250 6017 l 7214 6035 l
7180 6052 l 7147 6068 l 7117 6083 l 7090 6096 l 7065 6108 l
7043 6118 l 7025 6127 l 7010 6134 l 6998 6140 l 6989 6144 l
6975 6150 l gs col0 s gr gr
% arrowhead
0 slj
n 7087 6052 m 6995 6141 l 7123 6135 l 7087 6052 l cp gs 0.00 setgray ef gr col0 s
% Polyline
2 slj
gs clippath
8433 3848 m 8521 3831 l 8493 3676 l 8471 3803 l 8404 3693 l cp
eoclip
n 7050 2400 m 7051 2400 l 7054 2401 l 7058 2401 l 7066 2403 l 7076 2404 l
7090 2407 l 7107 2410 l 7127 2414 l 7150 2418 l 7177 2424 l
7206 2430 l 7238 2437 l 7271 2445 l 7306 2454 l 7343 2463 l
7381 2474 l 7419 2486 l 7458 2499 l 7498 2513 l 7538 2528 l
7579 2545 l 7621 2564 l 7663 2585 l 7706 2608 l 7750 2634 l
7795 2662 l 7841 2694 l 7887 2728 l 7933 2766 l 7980 2807 l
8025 2850 l 8068 2895 l 8109 2942 l 8147 2988 l 8181 3034 l
8213 3080 l 8241 3125 l 8267 3169 l 8290 3212 l 8311 3254 l
8330 3296 l 8347 3337 l 8362 3377 l 8376 3417 l 8389 3456 l
8401 3494 l 8412 3532 l 8421 3569 l 8430 3604 l 8438 3637 l
8445 3669 l 8451 3698 l 8457 3725 l 8461 3748 l 8465 3768 l
8468 3785 l 8471 3799 l 8472 3809 l
8475 3825 l gs col0 s gr gr
% arrowhead
0 slj
n 8404 3693 m 8471 3803 l 8493 3676 l 8404 3693 l cp gs 0.00 setgray ef gr col0 s
% Polyline
2 slj
gs clippath
4970 2442 m 4959 2353 l 4803 2372 l 4928 2403 l 4814 2461 l cp
eoclip
n 3375 3900 m 3375 3899 l 3376 3897 l 3377 3892 l 3378 3886 l 3380 3876 l
3383 3863 l 3386 3848 l 3391 3828 l 3396 3806 l 3402 3781 l
3409 3753 l 3417 3722 l 3425 3689 l 3435 3655 l 3446 3619 l
3457 3581 l 3469 3543 l 3483 3504 l 3497 3464 l 3513 3423 l
3530 3383 l 3549 3341 l 3569 3299 l 3591 3257 l 3615 3214 l
3641 3170 l 3669 3125 l 3701 3080 l 3735 3034 l 3772 2988 l
3812 2941 l 3855 2895 l 3900 2850 l 3950 2804 l 4001 2762 l
4052 2723 l 4102 2687 l 4152 2655 l 4201 2625 l 4248 2599 l
4295 2576 l 4340 2555 l 4385 2536 l 4429 2519 l 4472 2504 l
4515 2490 l 4557 2477 l 4598 2466 l 4638 2456 l 4677 2447 l
4715 2439 l 4751 2432 l 4784 2426 l 4815 2420 l 4843 2415 l
4868 2411 l 4890 2408 l 4908 2406 l 4922 2404 l 4933 2402 l
4950 2400 l gs col0 s gr gr
% arrowhead
0 slj
n 4814 2461 m 4928 2403 l 4803 2372 l 4814 2461 l cp gs 0.00 setgray ef gr col0 s
/Times-Roman ff 360.00 scf sf
5925 6225 m
gs 1 -1 sc (Initial[n]) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 360.00 scf sf
8100 4275 m
gs 1 -1 sc (Dispatching) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 360.00 scf sf
3675 4350 m
gs 1 -1 sc (Prepared) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 360.00 scf sf
5925 2550 m
gs 1 -1 sc (Polling) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
4050 3300 m
gs 1 -1 sc (query\(\)) col0 sh gr
/Times-Roman ff 270.00 scf sf
7800 3225 m
gs 1 -1 sc (check\(\)) dup sw pop neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
2475 6375 m
gs 1 -1 sc (Working) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
3900 5400 m
gs 1 -1 sc (prepare\(\)) col0 sh gr
/Times-Roman ff 270.00 scf sf
8025 5325 m
gs 1 -1 sc (dispatch\(\)) dup sw pop neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
9150 2250 m
gs 1 -1 sc (Working) dup sw pop 2 div neg 0 rm col0 sh gr
$F2psEnd
rs
docs/reference/glib/mainloop-states.fig
+65
View File
@@ -0,0 +1,65 @@
#FIG 3.2
Landscape
Center
Inches
Letter
100.00
Single
-2
1200 2
6 8625 6000 9975 6600
4 1 0 50 0 0 18 0.0000 4 240 1290 9300 6225 Initial[n+1]\001
4 1 0 50 0 0 18 0.0000 4 255 1335 9300 6540 (Recursion)\001
-6
2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
3225 6525 3225 6000 1800 6000 1800 6525 3225 6525
2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
1 1 2.00 90.00 120.00
1 1 2.00 90.00 120.00
3225 6000 3825 5475
2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
6975 6375 6975 5775 4875 5775 4875 6375 6975 6375
2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
1 1 2.00 90.00 120.00
1 1 2.00 90.00 120.00
8025 5550 8475 5925
2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
10125 6675 10125 5850 8475 5850 8475 6675 10125 6675
2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
9150 4425 9150 3825 7050 3825 7050 4425 9150 4425
2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
7050 2700 7050 2100 4950 2100 4950 2700 7050 2700
2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
4725 4500 4725 3900 2625 3900 2625 4500 4725 4500
2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
9750 2400 9750 1875 8475 1875 8475 2400 9750 2400
2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
1 1 2.00 90.00 120.00
1 1 2.00 90.00 120.00
8047 2868 8475 2400
3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
1 1 2.00 90.00 120.00
4875 6075 3825 5550 3300 4500
0.000 -1.000 0.000
3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
1 1 2.00 90.00 120.00
8475 4500 8100 5400 6975 6150
0.000 -1.000 0.000
3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
1 1 2.00 90.00 120.00
7050 2400 8025 2850 8475 3825
0.000 -1.000 0.000
3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
1 1 2.00 90.00 120.00
3375 3900 3900 2850 4950 2400
0.000 -1.000 0.000
4 1 0 50 0 0 24 0.0000 4 315 1290 5925 6225 Initial[n]\001
4 1 0 50 0 0 24 0.0000 4 330 1770 8100 4275 Dispatching\001
4 1 0 50 0 0 24 0.0000 4 330 1320 3675 4350 Prepared\001
4 1 0 50 0 0 24 0.0000 4 330 1050 5925 2550 Polling\001
4 0 0 50 0 0 18 0.0000 4 255 825 4050 3300 query()\001
4 2 0 50 0 0 18 0.0000 4 255 855 7800 3225 check()\001
4 1 0 50 0 0 18 0.0000 4 255 990 2475 6375 Working\001
4 0 0 50 0 0 18 0.0000 4 255 1050 3900 5400 prepare()\001
4 2 0 50 0 0 18 0.0000 4 255 1140 8025 5325 dispatch()\001
4 1 0 50 0 0 18 0.0000 4 255 990 9150 2250 Working\001
docs/reference/glib/mainloop-states.gif
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.9 KiB

docs/reference/glib/mainloop-states.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

docs/reference/glib/meson.build
+104
View File
@@ -0,0 +1,104 @@
if get_option('gtk_doc')
subdir('xml')
ignore_headers = [
'gallocator.h',
'gdatasetprivate.h',
'glibintl.h',
'gbsearcharray.h',
'glib-private.h',
'gmoduleconf.h',
'grcboxprivate.h',
'gstdioprivate.h',
'gthreadprivate.h',
'gunibreak.h',
'gunicomp.h',
'gunidecomp.h',
'gunichartables.h',
'glib_probes.h',
'glib_trace.h',
'libcharset.h',
'gdebug.h',
'gprintfint.h',
'gmirroringtable.h',
'gscripttable.h',
'glib-mirroring-tab',
'gnulib',
'pcre',
'update-pcre',
'gbytesprivate.h',
'gvariant-internal.h',
'gvariant-serialiser.h',
'gvariant-core.h',
'gvarianttypeinfo.h',
'gwakeup.h',
'gtranslit-data.h',
'glib-init.h',
'gconstructor.h',
'valgrind.h',
'gutilsprivate.h',
'gvalgrind.h',
'dirent.h',
]
docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
version_conf = configuration_data()
version_conf.set('GLIB_VERSION', meson.project_version())
configure_file(
input: 'version.xml.in',
output: 'version.xml',
configuration: version_conf
)
gnome.gtkdoc('glib',
main_xml : 'glib-docs.xml',
namespace : 'g',
mode : 'none',
src_dir : [ 'glib', 'gmodule' ],
dependencies : libglib_dep,
scan_args : gtkdoc_common_scan_args + [
'--ignore-headers=' + ' '.join(ignore_headers),
],
content_files : [
'cross.xml',
'running.xml',
'building.xml',
'changes.xml',
'compiling.xml',
'programming.xml',
'resources.xml',
'regex-syntax.xml',
'glib-gettextize.xml',
'gtester.xml',
'gtester-report.xml',
'gvariant-varargs.xml',
'gvariant-text.xml',
],
expand_content_files : [
'compiling.xml',
],
html_assets : [
'file-name-encodings.png',
'mainloop-states.gif',
'Sorted_binary_tree_breadth-first_traversal.svg',
'Sorted_binary_tree_inorder.svg',
'Sorted_binary_tree_postorder.svg',
'Sorted_binary_tree_preorder.svg',
],
fixxref_args: [
'--html-dir=' + docpath,
],
install: true)
endif
if get_option('man')
manpages = ['glib-gettextize', 'gtester', 'gtester-report']
foreach page : manpages
custom_target(page + '-man',
input: page + '.xml',
output: page + '.1',
command: xsltproc_command,
install: true,
install_dir: man1_dir)
endforeach
endif
docs/reference/glib/programming.xml
+67
View File
@@ -0,0 +1,67 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-programming">
<refmeta>
<refentrytitle>Writing GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Writing GLib Applications</refname>
<refpurpose>
General considerations when programming with GLib
</refpurpose>
</refnamediv>
<refsect1>
<title>Writing GLib Applications</title>
<refsect2>
<title>Threads</title>
<para>
The general policy of GLib is that all functions are invisibly threadsafe
with the exception of data structure manipulation functions, where, if
you have two threads manipulating the <emphasis>same</emphasis> data
structure, they must use a lock to synchronize their operation.
</para>
<para>
GLib creates a worker thread for its own purposes so GLib applications
will always have at least 2 threads.
</para>
<para>
See the sections on <link linkend="glib-Threads">threads</link> and
<link linkend="glib-Thread-Pools">threadpools</link> for GLib APIs that
support multithreaded applications.
</para>
</refsect2>
<refsect2>
<title>Security</title>
<para>
When writing code that runs with elevated privileges, it is important
to follow some basic rules of secure programming. David Wheeler has an
excellent book on this topic,
<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
</para>
<para>
When it comes to GLib and its associated libraries, GLib and
GObject are generally fine to use in code that runs with elevated
privileges; they don't load modules (executable code in shared objects)
or run other programs 'behind your back'. GIO has to be used
carefully in privileged programs, see the <ulink url="http://developer.gnome.org/gio/stable/ch02.html">GIO documentation</ulink> for details.
</para>
</refsect2>
</refsect1>
</refentry>
docs/reference/glib/regex-syntax.xml
+2531
View File
File diff suppressed because it is too large Load Diff
docs/reference/glib/resources.xml
+77
View File
@@ -0,0 +1,77 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-resources" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Mailing lists and bug reports</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Mailing lists and bug reports</refname>
<refpurpose>
Getting help with GLib
</refpurpose>
</refnamediv>
<refsect1>
<title>Filing a bug report or feature request</title>
<para>
If you encounter a bug, misfeature, or missing feature in GLib, please
file a bug report on the issue tracker at
<ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
We'd also appreciate reports of incomplete or misleading information in
the GLib documentation; file those with the ‘Documentation’ label.
</para>
<para>
Don't hesitate to file a bug report, even if you think we may know
about it already, or aren't sure of the details. Just give us as much
information as you have, and if it's already fixed or has already been
discussed, we'll add a note to that effect in the report.
</para>
<para>
The issue tracker should definitely be used for feature requests, it's
not only for bugs. We track all GLib development in GitLab, so it's
the way to be sure the GLib developers won't forget about an issue.
</para>
</refsect1>
<refsect1>
<title>Code Contributions</title>
<para>
If you develop a bugfix or enhancement for GLib, please open a merge request
for that in GitLab as well. All branches must be offered under the terms of
the GNU LGPL license, so be sure you are authorized to give us the branch
under those terms.
</para>
<para>
If you want to discuss your branch before or after developing it, open a
topic on <ulink url="https://discourse.gnome.org/tags/glib">Discourse</ulink>.
But be sure to create the GitLab merge request as well; if the branch is only
on the list and not in GitLab, it's likely to slip through the cracks.
</para>
</refsect1>
<refsect1>
<title>Discussions and user questions</title>
<para>
The <ulink url="https://gitlab.gnome.org/GNOME/glib/issues">GLib issue tracker</ulink>
is meant for discussions with actionable topics. If you want to ask a question
about using GLib, or discuss new features, you should use
<ulink url="https://discourse.gnome.org/tags/glib">the glib tag on Discourse</ulink>.
</para>
</refsect1>
</refentry>
docs/reference/glib/running.xml
+411
View File
@@ -0,0 +1,411 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-running">
<refmeta>
<refentrytitle>Running GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Running GLib Applications</refname>
<refpurpose>
How to run and debug your GLib application
</refpurpose>
</refnamediv>
<refsect1>
<title>Running and debugging GLib Applications</title>
<refsect2>
<title>Environment variables</title>
<para>
The runtime behaviour of GLib applications can be influenced by a
number of environment variables.
</para>
<formalpara>
<title>Standard variables</title>
<para>
GLib reads standard environment variables like <envar>LANG</envar>,
<envar>PATH</envar>, <envar>HOME</envar>, <envar>TMPDIR</envar>,
<envar>TZ</envar> and <envar>LOGNAME</envar>.
</para>
</formalpara>
<formalpara>
<title>XDG directories</title>
<para>
GLib consults the environment variables <envar>XDG_DATA_HOME</envar>,
<envar>XDG_DATA_DIRS</envar>, <envar>XDG_CONFIG_HOME</envar>,
<envar>XDG_CONFIG_DIRS</envar>, <envar>XDG_CACHE_HOME</envar> and
<envar>XDG_RUNTIME_DIR</envar> for the various XDG directories.
For more information, see the <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG basedir spec</ulink>.
</para>
</formalpara>
<formalpara id="G_FILENAME_ENCODING">
<title><envar>G_FILENAME_ENCODING</envar></title>
<para>
This environment variable can be set to a comma-separated list of character
set names. GLib assumes that filenames are encoded in the first character
set from that list rather than in UTF-8. The special token "@locale" can be
used to specify the character set for the current locale.
</para>
</formalpara>
<formalpara id="G_BROKEN_FILENAMES">
<title><envar>G_BROKEN_FILENAMES</envar></title>
<para>
If this environment variable is set, GLib assumes that filenames are in
the locale encoding rather than in UTF-8. G_FILENAME_ENCODING takes
priority over G_BROKEN_FILENAMES.
</para>
</formalpara>
<formalpara id="G_MESSAGES_PREFIXED">
<title><envar>G_MESSAGES_PREFIXED</envar></title>
<para>
A list of log levels for which messages should be prefixed by the
program name and PID of the application. The default is to prefix
everything except <literal>G_LOG_LEVEL_MESSAGE</literal> and
<literal>G_LOG_LEVEL_INFO</literal>.
The possible values are
<literal>error</literal>,
<literal>warning</literal>,
<literal>critical</literal>,
<literal>message</literal>,
<literal>info</literal> and
<literal>debug</literal>.
You can also use the special values
<literal>all</literal> and
<literal>help</literal>.
</para>
<para>
This environment variable only affects the default log handler,
g_log_default_handler().
</para>
</formalpara>
<formalpara id="G_MESSAGES_DEBUG">
<title><envar>G_MESSAGES_DEBUG</envar></title>
<para>
A space-separated list of log domains for which informational
and debug messages should be printed. By default, these
messages are not printed.
</para>
<para>
You can also use the special value <literal>all</literal>.
</para>
<para>
This environment variable only affects the default log handler,
g_log_default_handler().
</para>
</formalpara>
<formalpara id="G-DEBUG:CAPS">
<title><envar>G_DEBUG</envar></title>
<para>
This environment variable can be set to a list of debug options,
which cause GLib to print out different types of debugging information.
<variablelist>
<varlistentry>
<term>fatal-warnings</term>
<listitem><para>Causes GLib to abort the program at the first call
to g_warning() or g_critical(). Use of this flag is not
recommended except when debugging.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fatal-criticals</term>
<listitem><para>Causes GLib to abort the program at the first call
to g_critical(). This flag can be useful during debugging and
testing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>gc-friendly</term>
<listitem><para>Newly allocated memory that isn't directly initialized,
as well as memory being freed will be reset to 0. The point here is
to allow memory checkers and similar programs that use Boehm GC alike
algorithms to produce more accurate results.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>resident-modules</term>
<listitem><para>All modules loaded by GModule will be made resident.
This can be useful for tracking memory leaks in modules which are
later unloaded; but it can also hide bugs where code is accessed
after the module would have normally been unloaded.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>bind-now-modules</term>
<listitem><para>All modules loaded by GModule will bind their symbols
at load time, even when the code uses %G_MODULE_BIND_LAZY.</para>
</listitem>
</varlistentry>
</variablelist>
The special value all can be used to turn on all debug options.
The special value help can be used to print all available options.
</para>
</formalpara>
<formalpara id="G_SLICE">
<title><envar>G_SLICE</envar></title>
<para>
This environment variable allows reconfiguration of the GSlice
memory allocator.
<variablelist>
<varlistentry>
<term>always-malloc</term>
<listitem><para>This will cause all slices allocated through
g_slice_alloc() and released by g_slice_free1() to be actually
allocated via direct calls to g_malloc() and g_free().
This is most useful for memory checkers and similar programs that
use Boehm GC alike algorithms to produce more accurate results.
It can also be in conjunction with debugging features of the system's
malloc() implementation such as glibc's MALLOC_CHECK_=2 to debug
erroneous slice allocation code, although
<literal>debug-blocks</literal> is usually a better suited debugging
tool.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>debug-blocks</term>
<listitem><para>Using this option (present since GLib 2.13) engages
extra code which performs sanity checks on the released memory
slices. Invalid slice addresses or slice sizes will be reported and
lead to a program halt. This option is for debugging scenarios.
In particular, client packages sporting their own test suite should
<emphasis>always enable this option when running tests</emphasis>.
Global slice validation is ensured by storing size and address
information for each allocated chunk, and maintaining a global
hash table of that data. That way, multi-thread scalability is
given up, and memory consumption is increased. However, the
resulting code usually performs acceptably well, possibly better
than with comparable memory checking carried out using external
tools.</para>
<para>An example of a memory corruption scenario that cannot be
reproduced with <literal>G_SLICE=always-malloc</literal>, but will
be caught by <literal>G_SLICE=debug-blocks</literal> is as follows:
<programlisting>
void *slist = g_slist_alloc (); /* void* gives up type-safety */
g_list_free (slist); /* corruption: sizeof (GSList) != sizeof (GList) */
</programlisting></para>
</listitem>
</varlistentry>
</variablelist>
The special value all can be used to turn on all options.
The special value help can be used to print all available options.
</para>
</formalpara>
<formalpara id="G_RANDOM_VERSION">
<title><envar>G_RANDOM_VERSION</envar></title>
<para>
If this environment variable is set to '2.0', the outdated
pseudo-random number seeding and generation algorithms from
GLib 2.0 are used instead of the newer, better ones. You should
only set this variable if you have sequences of numbers that were
generated with Glib 2.0 that you need to reproduce exactly.
</para>
</formalpara>
<formalpara id="LIBCHARSET_ALIAS_DIR">
<title><envar>LIBCHARSET_ALIAS_DIR</envar></title>
<para>
Allows to specify a nonstandard location for the
<filename>charset.aliases</filename> file that is used by the
character set conversion routines. The default location is the
<replaceable>libdir</replaceable> specified at compilation time.
</para>
</formalpara>
<formalpara id="TZDIR">
<title><envar>TZDIR</envar></title>
<para>
Allows to specify a nonstandard location for the timezone data files
that are used by the #GDateTime API. The default location is under
<filename>/usr/share/zoneinfo</filename>. For more information,
also look at the <command>tzset</command> manual page.
</para>
</formalpara>
<formalpara id="G_ENABLE_DIAGNOSTIC">
<title><envar>G_ENABLE_DIAGNOSTIC</envar></title>
<para>
If set to a non-zero value, this environment variable enables
diagnostic messages, like deprecation messages for GObject properties
and signals.
</para>
</formalpara>
<formalpara id="G_DEBUGGER">
<title><envar>G_DEBUGGER</envar></title>
<para>
When running on Windows, if set to a non-empty string, GLib will
try to interpret the contents of this environment variable as
a command line to a debugger, and run it if the process crashes.
The debugger command line should contain <literal>%p</literal> and <literal>%e</literal> substitution
tokens, which GLib will replace with the process ID of the crashing
process and a handle to an event that the debugger should signal
to let GLib know that the debugger successfully attached to the
process. If <literal>%e</literal> is absent, or if the debugger is not able to
signal events, GLib will resume execution after 60 seconds.
If <literal>%p</literal> is absent, the debugger won't know which process to attach to,
and GLib will also resume execution after 60 seconds.
</para>
<para>
Additionally, even if <envar>G_DEBUGGER</envar> is not set, GLib would still
try to print basic exception information (code and address) into
stderr.
</para>
<para>
By default the debugger gets a new console allocated for it.
Set the <envar>G_DEBUGGER_OLD_CONSOLE</envar> environment variable to any
non-empty string to make the debugger inherit the console of
the crashing process. Normally this is only used by the GLib
testsuite.
</para>
<para>
The exception handler is written with the aim of making it as
simple as possible, to minimize the risk of it invoking
buggy functions or running buggy code, which would result
in exceptions being raised recursively. Because of that
it lacks most of the amenities that one would expect of GLib.
Namely, it does not support Unicode, so it is highly advisable
to only use ASCII characters in <envar>G_DEBUGGER</envar>.
</para>
<para>
See also <link linkend="G_VEH_CATCH"><envar>G_VEH_CATCH</envar></link>.
</para>
</formalpara>
<formalpara id="G_VEH_CATCH">
<title><envar>G_VEH_CATCH</envar></title>
<para>
Catching some exceptions can break the program, since Windows
will sometimes use exceptions for execution flow control and
other purposes other than signalling a crash.
</para>
<para>
The <envar>G_VEH_CATCH</envar> environment variable augments
<ulink url="https://docs.microsoft.com/en-us/windows/desktop/debug/vectored-exception-handling">Vectored Exception Handling</ulink>
on Windows (see <link linkend="G_DEBUGGER"><envar>G_DEBUGGER</envar></link>), allowing GLib to catch more
exceptions. Set this variable to a comma-separated list of
hexademical exception codes that should additionally be caught.
</para>
<para>
By default GLib will only catch Access Violation, Stack Overflow and
Illegal Instruction <ulink url="https://docs.microsoft.com/en-us/windows/desktop/api/winnt/ns-winnt-_exception_record">exceptions</ulink>.
</para>
</formalpara>
</refsect2>
<refsect2 id="setlocale">
<title>Locale</title>
<para>
A number of interfaces in GLib depend on the current locale in which
an application is running. Therefore, most GLib-using applications should
call <function>setlocale (LC_ALL, "")</function> to set up the current
locale.
</para>
<para>
On Windows, in a C program there are several locale concepts
that not necessarily are synchronized. On one hand, there is the
system default ANSI code-page, which determines what encoding is used
for file names handled by the C library's functions and the Win32
API. (We are talking about the "narrow" functions here that take
character pointers, not the "wide" ones.)
</para>
<para>
On the other hand, there is the C library's current locale. The
character set (code-page) used by that is not necessarily the same as
the system default ANSI code-page. Strings in this character set are
returned by functions like <function>strftime()</function>.
</para>
</refsect2>
<para>
GLib ships with a set of Python macros for the GDB debugger. These includes pretty
printers for lists, hashtables and GObject types. It also has a backtrace filter
that makes backtraces with signal emissions easier to read.
</para>
<para>
To use this you need a version of GDB that supports Python scripting; anything
from 7.0 should be fine. You then need to install GLib in the same prefix as
GDB so that the Python GDB autoloaded files get installed in the right place
for GDB to pick up.
</para>
<para>
General pretty printing should just happen without having to do anything special.
To get the signal emission filtered backtrace you must use the "new-backtrace" command
instead of the standard one.
</para>
<para>
There is also a new command called gforeach that can be used to apply a command
on each item in a list. E.g. you can do
<programlisting>
gforeach i in some_list_variable: print *(GtkWidget *)l
</programlisting>
Which would print the contents of each widget in a list of widgets.
</para>
<refsect2>
<title>SystemTap</title>
<para>
<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink> is a dynamic whole-system
analysis toolkit. GLib ships with a file <filename>libglib-2.0.so.*.stp</filename> which defines a
set of probe points, which you can hook into with custom SystemTap scripts.
See the files <filename>libglib-2.0.so.*.stp</filename>, <filename>libgobject-2.0.so.*.stp</filename>
and <filename>libgio-2.0.so.*.stp</filename> which
are in your shared SystemTap scripts directory.
</para>
</refsect2>
<refsect2>
<title>Memory statistics</title>
<para>
g_mem_profile() will output a summary g_malloc() memory usage, if memory
profiling has been enabled by calling
<literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup.
</para>
<para>
If GLib has been configured with <option>--enable-debug=yes</option>,
then g_slice_debug_tree_statistics() can be called in a debugger to
output details about the memory usage of the slice allocator.
</para>
</refsect2>
</refsect1>
</refentry>
docs/reference/glib/version.xml.in
+1
View File
@@ -0,0 +1 @@
@GLIB_VERSION@

Some files were not shown because too many files have changed in this diff Show More