{"id":15634868,"url":"https://github.com/jhass/crystal-gobject","last_synced_at":"2025-04-14T13:11:44.497Z","repository":{"id":26972933,"uuid":"30436479","full_name":"jhass/crystal-gobject","owner":"jhass","description":"gobject-introspection for Crystal","archived":false,"fork":false,"pushed_at":"2021-11-15T12:33:46.000Z","size":4080,"stargazers_count":125,"open_issues_count":17,"forks_count":13,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-03-28T02:14:23.237Z","etag":null,"topics":["crystal","gdk","glib","glue","gobject-introspection","gtk","libnotify","shard","usable"],"latest_commit_sha":null,"homepage":"","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jhass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-06T22:43:59.000Z","updated_at":"2025-02-28T14:03:49.000Z","dependencies_parsed_at":"2022-07-27T09:02:41.697Z","dependency_job_id":null,"html_url":"https://github.com/jhass/crystal-gobject","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhass%2Fcrystal-gobject","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhass%2Fcrystal-gobject/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhass%2Fcrystal-gobject/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhass%2Fcrystal-gobject/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhass","download_url":"https://codeload.github.com/jhass/crystal-gobject/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248886324,"owners_count":21177643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crystal","gdk","glib","glue","gobject-introspection","gtk","libnotify","shard","usable"],"created_at":"2024-10-03T10:58:12.533Z","updated_at":"2025-04-14T13:11:42.523Z","avatar_url":"https://github.com/jhass.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gobject-introspection for [Crystal](http://crystal-lang.org)\n\nThe primary purpose of this shard is to provide compile-time generated\nbindings to libraries supporting GObject Introspection, so for example Gtk.\n\nSecondarily this project also aims to provide hand written extensions and\noverrides for the more popular GObject based libraries that make the bindings\nmore friendly to use and allow users to write more idiomatic Crystal.\nIn the midterm these should be extracted to their own shards that depend on this one.\n\nThis should be useable for simple projects but usually still requires familarity with\nthe C interface and usage of the original library. There's most likely still\nincorrect code generated, some methods may not even compile when invoked as\nCrystal does semantic checks only then. So this should be considered a work in\nprogress and contributions are very welcome!\n\n## Install\n\nInstall like any other shard. Additionally you'll need gobject-introspection installed\nas well as the GObject based library you want to use and its typelib file needs to be\navailable.\n\n### Debian\n\n```\nsudo apt install libgirepository1.0-dev\n```\n\n### Fedora\n\n```\nsudo dnf install gobject-introspection-devel\n```\n\n## Usage\n\nInclude in your shard.yml:\n```yaml\ndependencies:\n  gobject:\n    github: jhass/crystal-gobject\n    version: ~\u003e 0.10.0\n```\n\nFor libraries that have convenience wrappers you just require them under the `gobject`\nnamespace. For example:\n\n```cr\nrequire \"gobject/gdk\"\n```\n\nGtk specifically has a convenience wrapper that starts the mainloop automatically:\n\n```cr\nrequire \"gobject/gtk/autorun\"\n```\n\nHowever the main entry point is the `require_gobject` macro:\n\n\n```cr\nrequire \"gobject\"\nrequire_gobject \"Gio\"\n```\n\nThis will replace itself with the entire generated binding code for, in this case,\nGio and its dependencies.\n\nThere's a very work in progress documentation generator under the `gi-doc` target.\nNote it is a modified version of the Crystal compiler's doc generator and thus\ncompiles almost the entire compiler, thus compiling this tool takes as much time\nand resources as compiling the compiler does. Also libraries such as Gtk are huge! Generating\nfor Gtk and its dependencies will take a long time and generate about a gigabyte\nof documentation.\n\n## Samples\n\nClone the repo and give the samples a try:\n```\ncd samples\ncrystal run gtk_hello_world.cr\n```\n\nTo run the samples you will also need the Gtk development package.\n\nOn Debian you can install it with:\n```\nsudo apt install libgtk-3-dev\n```\n\nOn Fedora:\n```\nsudo dnf install gtk3-devel\n```\n\n## I'm on Linux and I'm getting random crashes (segmentation faults)\n\nUsing GTK or another library that spawns threads? Please try adding\n[crystal-malloc_pthread_shim](https://github.com/jhass/crystal-malloc_pthread_shim) to your project.\nIf that does not help, please open an issue with a, ideally minimal, example to reproduce the crash!\n\n\n## Contributing\n\nPull requests are welcome! If you encounter a bug, the first step is to produce\nthe most minimal example that reproduces it. Currently this has no testsuite,\nso the samples funciton as a sort of manual testsuite. That means including this minimal\nexample into an issue or pull request will not only allow others to verify the bug,\nbut also prevent it from reappearing as a regression.\n\nRunning `src/generator/build_namespace.cr` directly is a good way to inspect the generated code.\nAn alternative is to add `{% debug() %}` to the end of the `require_gobject`\nmacro definition in `src/gobject.cr`.\n\n### Architecture\n\ngobject-introspection is itself a C library, so we need to have bindings for it.\nIt is itself introspectable and we make use of that, however there's a bootstrapping\nproblem if we would try to use the main `require_gobject` macro for that, there are\nno bindings for what it's based on! So we have a second generator that writes the output\nto static files under `src/generated` under the target `gi-generator`. The initial version\nof this was bootstrapped using hand-written bindings. A good quick check whether any changes\nyou did still work, is to build and run this target twice, the first time to update the generated\nbindings and the second time to see if they still compile and produce the same output.\n\n`src/generator` has the driver code for any of the generators and tools. `src/g_i_repository`\ncontains the classes that define the Crystal code for each of the GObject Introspection info types.\n\nThe `gi-dump` target tries to completely map out all info that's present in a typelib, that is\nhow the current bindings see that info. Look at its options, you'll need to make use\nof them to drill in, otherwise it's just too much output due to how it displays\nthe same infos all over again and again recursively.\n\nFor now convenience extensions and overrides go under `src/library_name`, so for example `src/gtk` for Gtk or `src/g_lib` for GLib.\nThe future prospect is to have them live in their own shards that depend on this one.\n\n## Library specific shards\n\nLike mentioned above, we want shards that collect any convenience extensions and overrides to the code this library generates.\nHere's a well known list of  them:\n\n- [cairo-gobject](https://github.com/viachpaliy/cairo-gobject) - Cairo bindings for crystal-gobject.\n- [gtk_custom_widgets](https://github.com/viachpaliy/gtk_custom_widgets) - collection of custom widgets.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhass%2Fcrystal-gobject","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhass%2Fcrystal-gobject","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhass%2Fcrystal-gobject/lists"}