Gir.Core is a C# wrapper for GObject-based libraries like GTK for user interfaces.
This project aims to provide a complete set of APIs for writing rich cross-platform user interfaces and multimedia programs. It is built upon the well-established GObject Introspection framework for language bindings.
- Idiomatic C#: An API which feels natural to C# developers (including the async/await feature).
- Simplicity: Memory management is handled automatically, greatly simplifying the C-API.
- Complete API: Support for the entire GTK and GStreamer stack, enabling feature-rich applications which deeply integrate with the OS.
- Declarative UI: A declarative syntax for creating GTK UIs (See the DeclarativeUI Sample). User interfaces may also be created the traditional way and/or with GtkBuilder XML.
- Extensibility: Allows 3rd party developers to write bindings for other GObject-based libraries, achieving full interoperability between them.
We are currently in a period of heavy iteration over the core internals of the project. The code is under heavy development and not ready for production. There is currently no nuget package available.
Library | Description | Level of Support |
---|---|---|
GTK 3 | UI-Toolkit | Partial |
GStreamer | Multimedia Framework | Partial |
Cairo | Graphics Library | Partial |
Pango | Font/Text Library | Partial |
DBus | Library for inter-process communication | Partial (via GIO) |
GdkPixbuf | Image loading in various formats | Partial |
GTK 4 | UI-Toolkit | Planned |
libhandy | Convergent UI for GTK on Mobile | Planned |
libchamplain | Library to display maps | Planned |
WebKitGTK | Browser Engine | Planned |
JavaScriptCore | JavaScript engine for WebKit | Planned |
Anyone who wants to help is very welcome. If you want to start working on the project, take a look at our Good First Issues or get in touch by starting a Discussion.
We have a matrix room for discussing gir.core. Please join if you'd like to help (or just want to chat!)
https://matrix.to/#/#gircore:matrix.org?via=matrix.org
To build the project locally in debug mode follow these steps. Make sure to initialise submodules with --recursive
otherwise the gir-files
directory will not be loaded properly.
$ git clone --recursive https://github.com/gircore/gir.core.git
$ cd gir.core/src/Generation/Build
$ dotnet run
If you want to build using Windows please see the accompanying documentation.
There are some options which can be used to influence the code generation:
--release
: Execute the targets with the Release configuration. If not specified the Debug configuration is used.--xml-documentation
: Generate the xml documentation.--generate-comments
: Take over comments from gir file into the wrapper code. Be aware of the LGPL license of the comments.--targets <targets>
: A list of targets to run or list.--version <version>
: Specify the version number of thebuild
.--disable-async
: Runs the generator synchronously (useful for debugging if something goes wrong)
To get a full list of available options use --help
.
Supported targets are:
generate
: Generates the source code files. Recognizescomments
option.build
: Builds the project withDebug
orRelease
configuration. Recognizesxml-documentation
andversion
option. Depends ongenerate
target.integration
: Builds the integration library.unittest
: Execute unit tests withDebug
orRelease
configuration. Depends onbuild
.integrationtest
: Execute integrations tests withDebug
orRelease
configuration. Depends onunittest
.systemtest
: Execute integration tests that require system services like the DBus System Bus or Wayland Display Server. Depends onintegrationtest
.pack
: Packs the libraries into theNuget
folder in the project root. Recognizesversion
option. Depends onbuild
.clean
: Cleanssamples
andbuild
output including generated source code files.samples
: Builds the sample applications withDebug
orRelease
configuration. Depends onbuild
andintegration
.
If no target is specified the build
target is executed.
If you want to clean your debug build just run:
$ dotnet run -- --targets clean
If you want to generate the xml documentation, build the samples and run the test cases in debug mode just run:
$ dotnet run -- --xml-documentation --targets test samples
If you want to build the wrappers in release mode just run
$ dotnet run -- --release
To use the newly build libraries in your project just add a reference to the csproj file of the project you want to use, e.g:
$ dotnet add reference [RepoPath]/Libs/Gtk/Gtk.csproj
The folder structure in this repository is organized as follows:
- src/Generation/Build: The build tool determines which projects to build and generates the libraries. Everything works automatically.
- src/Generation/GirLoader: A library for reading and resolving GObject Introspection repositories.
- src/Generation/Generator: Code generator generates C# code from GObject Introspection data.
- src/Integration: Optional source generators to reduce boilerplate code in your projects.
- src/Libs: Contains manually written code for libraries. The generator outputs code here.
- src/Samples: Example programs using GTK, GStreamer, and others.
- src/Tests: Unit and Integration tests.
- ext/gir-files: Introspection data from gircore/gir-files.
The code in the library folder is not complete because most of the code is generated when the build tool is run.
Gir.Core is licensed under the terms of the MIT-License. Please see the license file for further information.
The Gir.Core logo is built upon the original GTK logo by Andreas Nilsson which is licensed under the GNU Free Documentation License and was relicensed under CC BY-SA 3.0. Therefore the Gir.Core logo is licensed under the CC BY-SA 3.0, too.