luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 11:26:16 +01:00
Code Issues Packages Projects Releases Wiki Activity
8440742c12
glib/docs/reference/girepository/migrating-gi.md

113 lines
6.9 KiB
Markdown
Raw Normal View History

docs: Add migration guide for libgirepository This covers all the API changes from girepository-1.0 to girepository-2.0 so far. It was generated by manually looking through the changes in `git diff af36393e6.. -- girepository/*.h`. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-05 17:42:31 +01:00
Title: Migrating from girepository-1.0 to girepository-2.0
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2014 GNOME Foundation
# Migrating from girepository-1.0 to girepository-2.0
libgirepository was originally part of
[gobject-introspection](https://gitlab.gnome.org/GNOME/gobject-introspection/),
where it was prototyped for a number of years.
Now that it’s considered stable (for a long time), it’s been moved to
[glib](https://gitlab.gnome.org/GNOME/glib/) in order to simplify the build
process of the two modules.
As part of this move, the API version has been bumped from 1.0 to 2.0, and some
fairly straightforward API changes have been made. Note that the GIR version
was previously 2.0, and is now 3.0 — so the new version of libgirepository uses
`girepository-2.0.pc` and `GIRepository-3.0.typelib`.
The main change between the two versions of libgirepository is that it now uses
[type@GObject.TypeInstance] as the basis of its type system, rather than simple
C struct aliasing. This means that [type@GIRepository.BaseInfo] instances are
now reference counted using [method@GIRepository.BaseInfo.ref] and
[method@GIRepository.BaseInfo.unref].
It also means that runtime cast macros such as [func@GIRepository.CALLABLE_INFO]
are now available. Using these instead of simple C casts can improve the runtime
type safety of your code.
Stack allocation of some [type@GIRepository.BaseInfo] subtypes is still
possible, but they must now be cleared using
[method@GIRepository.BaseInfo.clear] once finished with. Previously this wasn’t
necessary.
As part of moving the code over, the symbol prefix has changed from `g_` to
`gi_` — this has affected every API in the library, but trivially.
The types of various function arguments have changed — for example from
`guint32` to `size_t` for most offsets. This will require minor adjustments in
your code if integer type warnings are enabled.
## API replacements from version 1.0 to 2.0
| girepository-1.0 | girepository-2.0 |
|------------------|------------------|
| `GI_CHECK_VERSION` | [func@GLib.CHECK_VERSION] |
| `g_arg_info_get_closure` | [method@GIRepository.ArgInfo.get_closure_index] |
| `g_arg_info_get_destroy` | [method@GIRepository.ArgInfo.get_destroy_index] |
| `g_arg_info_get_type` | [method@GIRepository.ArgInfo.get_type_info] |
| `g_arg_info_load_type` | [method@GIRepository.ArgInfo.load_type_info] |
| - | [method@GIRepository.BaseInfo.ref] and [method@GIRepository.BaseInfo.unref] |
girepository: Make GIInfoType private Eventually, we want to move to using `GType` directly for everything, since `GIBaseInfo` and its subclasses are all using `GTypeInstance`. However, that requires quite a lot of changes and we’re about to hit the API freeze. So do the smallest set of changes possible to remove `GIInfoType` and related functions from the public API, which gives us freedom to make more changes later without breaking API. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-08 13:35:23 +01:00
| `g_base_info_get_type` | Use type checking macros like [func@GIRepository.IS_OBJECT_INFO], or raw [type@GObject.Type]s with [func@GObject.TYPE_FROM_INSTANCE] |
| `g_info_new` | Removed with no replacement, use [method@GIRepository.find_by_name] and related APIs |
docs: Add migration guide for libgirepository This covers all the API changes from girepository-1.0 to girepository-2.0 so far. It was generated by manually looking through the changes in `git diff af36393e6.. -- girepository/*.h`. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-05 17:42:31 +01:00
| `g_callable_info_invoke` arguments | `is_method` and `throws` dropped in [method@GIRepository.CallableInfo.invoke] |
| `g_constant_info_get_type` | [method@GIRepository.ConstantInfo.get_type_info] |
| `g_field_info_get_type` | [method@GIRepository.FieldInfo.get_type_info] |
girepository: Fix declaration of ‘find using interfaces’ methods Fix the declaration and documentation of `gi_object_info_find_method_using_interfaces()` and `gi_object_info_find_vfunc_using_interfaces()`. The documentation was wrong when I wrote it: the value returned is the object or interface which declares the method or vfunc, not the one which implements it. The returned declarer info may be a `GIObjectInfo` or a `GIInterfaceInfo`. Since those two types have no subtype relation between them, the return type has to be changed to `GIBaseInfo`. Using `GIObjectInfo` would have been fine in girepository-1.0 because all `*Info` types were aliases of each other — but since the move to `GTypeInstance` this is no longer true. A unit test will be in the following commit. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Fixes: #3246
2024-02-05 19:40:03 +01:00
| `g_object_info_find_method_using_interfaces` and `g_object_info_find_vfunc_using_interfaces` | The `implementor` out argument has been renamed to `declarer` and is now of type [type@GIRepository.BaseInfo] |
docs: Add migration guide for libgirepository This covers all the API changes from girepository-1.0 to girepository-2.0 so far. It was generated by manually looking through the changes in `git diff af36393e6.. -- girepository/*.h`. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-05 17:42:31 +01:00
| `g_object_info_get_type_init` | [method@GIRepository.ObjectInfo.get_type_init_function_name] |
| `g_object_info_get_ref_function` | [method@GIRepository.ObjectInfo.get_ref_function_name] |
| `g_object_info_get_unref_function` | [method@GIRepository.ObjectInfo.get_unref_function_name] |
| `g_object_info_get_set_value_function` | [method@GIRepository.ObjectInfo.get_set_value_function_name] |
| `g_object_info_get_get_value_function` | [method@GIRepository.ObjectInfo.get_get_value_function_name] |
| `g_property_info_get_type` | [method@GIRepository.PropertyInfo.get_type_info] |
| `g_registered_type_info_get_type_init` | [method@GIRepository.RegisteredTypeInfo.get_type_init_function_name] |
| `g_irepository_*` | `gi_repository_*` |
| `g_irepository_get_default` | Singleton object removed; create separate [class@GIRepository.Repository] instances instead |
| `g_irepository_get_search_path` and `g_irepository_get_library_path` | Now return arrays rather than linked lists |
| `g_irepository_enumerate_versions` | Now returns an array rather than a linked list |
girepository: Add length ‘out’ arguments to several getter methods This makes them consistent with the other getter methods in `GIRepository` which return lists/arrays. It’s useful to return the length, as that means the caller doesn’t have to work it out by iterating over the entire array. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-07 16:44:21 +01:00
| `g_irepository_get_immediate_dependencies`, `g_irepository_get_dependencies` and `g_irepository_get_loaded_namespaces` | Now additionally return a length argument |
docs: Add missing migration guide for gi_repository_get_shared_libraries() Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-08 15:34:32 +01:00
| `g_irepository_get_shared_library` | [method@GIRepository.get_shared_libraries] |
docs: Add migration guide for libgirepository This covers all the API changes from girepository-1.0 to girepository-2.0 so far. It was generated by manually looking through the changes in `git diff af36393e6.. -- girepository/*.h`. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-05 17:42:31 +01:00
| `g_irepository_dump` | Takes structured `input_filename` and `output_filename` arguments rather than a single formatted string |
| `g_function_invoker_destroy` | `gi_function_invoker_clear()` |
| `g_struct_info_get_copy_function` | [method@GIRepository.StructInfo.get_copy_function_name] |
| `g_struct_info_get_free_function` | [method@GIRepository.StructInfo.get_free_function_name] |
| `g_type_info_get_array_length` and `g_type_info_get_array_fixed_size` | Split success and failure return values out into a new out-argument and return value |
| `g_type_info_get_array_length` | [method@GIRepository.TypeInfo.get_array_length_index] |
| `g_typelib_new_from_*` | All replaced with `gi_typelib_new_from_bytes()` |
gitypelib: Switch to refcounting Since `GITypelib` is exposed in the public libgirepository API, it needs to be a boxed type. So we either need to add a `copy` method to mirror the existing `free` method, or switch to refcounting. The latter option seems better, since a `GITypelib` contains internal state about open `GModule`s and the semantics for copying that would be potentially complex. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-07 15:38:05 +01:00
| `g_typelib_free` | [type@GIRepository.Typelib] is now a refcounted and boxed type, so use [method@GIRepository.Typelib.unref] |
docs: Add migration guide for libgirepository This covers all the API changes from girepository-1.0 to girepository-2.0 so far. It was generated by manually looking through the changes in `git diff af36393e6.. -- girepository/*.h`. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-05 17:42:31 +01:00
| `GI_FUNCTION_THROWS` and `GI_VFUNC_THROWS` | [method@GIRepository.CallableInfo.can_throw_gerror] |
giunioninfo: Split success and return value for get_discriminator_offset() Otherwise there’s no obvious suitable return value to return when the union is *not* discriminated. This is an API break, but libgirepository has not been in a stable release yet, so that’s fine. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-06 14:34:17 +01:00
| `g_union_info_get_discriminator_offset` | Split success and failure return values out into a new out-argument and return value |
docs: Add migration guide for libgirepository This covers all the API changes from girepository-1.0 to girepository-2.0 so far. It was generated by manually looking through the changes in `git diff af36393e6.. -- girepository/*.h`. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-05 17:42:31 +01:00
| `g_union_info_get_copy_function` | [method@GIRepository.UnionInfo.get_copy_function_name] |
| `g_union_info_get_free_function` | [method@GIRepository.UnionInfo.get_free_function_name] |
girepository: Make GIInfoType private Eventually, we want to move to using `GType` directly for everything, since `GIBaseInfo` and its subclasses are all using `GTypeInstance`. However, that requires quite a lot of changes and we’re about to hit the API freeze. So do the smallest set of changes possible to remove `GIInfoType` and related functions from the public API, which gives us freedom to make more changes later without breaking API. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
2024-02-08 13:35:23 +01:00
| `GIInfoType` | Use [type@GObject.Type] directly |
girepository: Drop GIBoxedInfo See the previous commit for details. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3245
2024-02-08 12:47:03 +01:00
| `GI_INFO_TYPE_BOXED` | Dropped in favour of [method@GIRepository.RegisteredTypeInfo.is_boxed] |
docs: Document girepository-2.0 utility program name changes Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-08 15:34:04 +01:00
## Utility program renames from version 1.0 to 2.0
| girepository-1.0 | girepository-2.0 |
|------------------|-------------------------|
| `g-ir-compiler` | `gi-compile-repository` |
| `g-ir-generate` | `gi-decompile-typelib` |
| `g-ir-inspect` | `gi-inspect-typelib` |
gi-decompile-typelib: Interpret --includedir as most-important-first This is a behaviour change from g-ir-generate, which treats it as least-important-first (the last directory on the command-line is searched first). gi-compile-repository --includedir and gcc -I are most-important-first (the first directory on the command-line is searched first) so it seems like it makes most sense to be consistent with that. Signed-off-by: Simon McVittie <smcv@collabora.com>
2024-02-14 12:25:46 +01:00
In addition, some command-line options have been changed.
The `--version` option for `g-ir-inspect` has been renamed to
gi-inspect-repository: Change --version argument to --typelib-version `--version` is conventionally used to find the version of the program itself. While that’s not currently implemented in `gi-inspect-repository`, let’s not box ourselves into a corner. Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-08 15:43:00 +01:00
`--typelib-version` in `gi-inspect-typelib`.
gi-decompile-typelib: Interpret --includedir as most-important-first This is a behaviour change from g-ir-generate, which treats it as least-important-first (the last directory on the command-line is searched first). gi-compile-repository --includedir and gcc -I are most-important-first (the first directory on the command-line is searched first) so it seems like it makes most sense to be consistent with that. Signed-off-by: Simon McVittie <smcv@collabora.com>
2024-02-14 12:25:46 +01:00
The `--includedir` option to `gi-decompile-typelib` treats the
given directories as most-important-first, consistent with
`gi-compile-repository --includedir` and `gcc -I`.
`g-ir-generate` treated `--includedir` options as least-important-first.
migrating-gi: Document command-line option removals From !3926, !3927. Signed-off-by: Simon McVittie <smcv@collabora.com>
2024-02-14 13:03:33 +01:00
The unimplemented `g-ir-compiler --module` option has been removed in
`gi-compile-repository`.
The unimplemented `g-ir-generate --shlib` option has been removed in
`gi-decompile-typelib`.
`gi-inspect-typelib` only accepts one namespace parameter. `g-ir-inspect`
accepted multiple namespaces, but would only inspect the first one,
with the others being ignored.
Reference in New Issue Copy Permalink