luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 03:16:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add migration guide for libgirepository

Browse Source 
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
This commit is contained in:
Philip Withnall 2024-02-05 16:42:31 +00:00
parent 59a818c28b
commit bad849347d
3 changed files with 82 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/girepository/girepository.toml.in
View File

@ -45,6 +45,7 @@ show_class_hierarchy = true
urlmap_file = "urlmap.js" urlmap_file = "urlmap.js"
# The same order will be used when generating the index # The same order will be used when generating the index
content_files = [ content_files = [
"migrating-gi.md",
] ]
content_images = [ content_images = [
] ]

5
docs/reference/girepository/meson.build
View File

@ -1,4 +1,8 @@
if get_option('documentation') and enable_gir if get_option('documentation') and enable_gir
expand_content_files = [
'migrating-gi.md',
]
girepository_toml = configure_file( girepository_toml = configure_file(
input: 'girepository.toml.in', input: 'girepository.toml.in',
output: 'girepository.toml', output: 'girepository.toml',
@ -21,5 +25,6 @@ if get_option('documentation') and enable_gir
'@INPUT1@', '@INPUT1@',
], ],
build_by_default: true, build_by_default: true,
depend_files: expand_content_files,
) )
endif endif

76
docs/reference/girepository/migrating-gi.md Normal file
View File

@ -0,0 +1,76 @@
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] |
| `g_base_info_get_type` | [method@GIRepository.BaseInfo.get_info_type] |
| `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] |
| `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 |
| `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()` |
| `GI_FUNCTION_THROWS` and `GI_VFUNC_THROWS` | [method@GIRepository.CallableInfo.can_throw_gerror] |
| `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] |