Merge branch 'monorepo-development' into monorepo

Package.swift

@@ -7,6 +7,7 @@ let package = Package(
     products: [ .library(name: "Gtk", targets: ["Gtk"]) ],
     dependencies: [
         .package(url: "https://github.com/rhx/gir2swift.git", branch: "main"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
     ],
     targets: [
         .systemLibrary(

Sources/GLib/GLib.docc/Building.md

@@ -0,0 +1,14 @@
+# Building
+
+Normally, you don't build this package directly, but you embed it into your own project (see <doc:Usage> above).
+However, you can build and test this module separately to ensure that everything works.
+
+Make sure you have all the prerequisites installed (see <doc:GettingStarted> above).
+After that, you can simply clone this repository and build the library and its unit tests
+(be patient, this will download all the required dependencies and take a while to compile)
+using:
+
+	git clone https://github.com/rhx/SwiftGLib.git
+	cd SwiftGLib
+    swift build
+    swift test

Sources/GLib/GLib.docc/Documentation.md

@@ -0,0 +1,23 @@
+# Documentation
+
+You can generate documentation using the
+[DocC plugin](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/).
+This is also the documentation that is auto-generated at
+[https://rhx.github.io/SwiftGLib/](https://rhx.github.io/SwiftGLib/)
+
+## Using DocC
+
+To preview documentation matching your local installation, simply run
+
+    swift package --disable-sandbox preview-documentation
+
+then navigate to the URL shown for the local preview server.  Make sure you have JavaScript enabled in your browser.
+
+## Using Jazzy
+
+Alternatively, you can create static documentation using [jazzy](https://github.com/realm/jazzy).
+Make sure you have [sourcekitten](https://github.com/jpsim/SourceKitten) and [jazzy](https://github.com/realm/jazzy) installed, e.g. on macOS (x86_64):
+
+	brew install ruby sourcekitten
+	/usr/local/opt/ruby/bin/gem install jazzy
+	./generate-jazzy.sh

Sources/GLib/GLib.docc/GettingStarted.md

@@ -0,0 +1,42 @@
+# Getting Started
+
+This section contains the information to get you started in setting up the pre-requisites for building this library.
+You can then add this package as a dependency to your own project (see <doc:Usage> below).
+
+To build, download Swift from https://swift.org/download/ -- if you are using macOS, make sure you have the command line tools installed as well). Test that your compiler works using `swift --version`, which should give you something like
+
+	$ swift --version
+    swift-driver version: 1.87.3 Apple Swift version 5.9.2 (swiftlang-5.9.2.2.56 clang-1500.1.0.2.5)
+    Target: arm64-apple-macosx14.0
+
+on macOS, or on Linux you should get something like:
+
+	$ swift --version
+	Swift version 5.9.2 (swift-5.9.2-RELEASE)
+	Target: x86_64-unknown-linux-gnu
+
+## GLib 2.56 or higher
+
+These Swift wrappers have been tested with glib-2.56, 2.58, 2.60, 2.62, 2.64, 2.66, 2.68, 2.70, 2.72, 2.73, 2.74, 2.76, and 2.78.  They should work with higher versions, but YMMV.  Also make sure you have `gobject-introspection` and its `.gir` files installed.
+
+### Linux
+
+#### Ubuntu
+
+On Ubuntu 18.04, 20.04, and 22.04 you can use the glib that comes with the distribution.  Just install with the `apt` package manager:
+
+	sudo apt update
+	sudo apt install libglib2.0-dev glib-networking gobject-introspection libgirepository1.0-dev libxml2-dev jq
+
+#### Fedora
+
+On Fedora 29, you can use the gtk that comes with the distribution.  Just install with the `dnf` package manager:
+
+	sudo dnf install glib2-devel gobject-introspection-devel libxml2-devel jq
+
+### macOS
+
+On macOS, you can install glib using HomeBrew (for setup instructions, see http://brew.sh):
+
+	brew update
+	brew install glib glib-networking gobject-introspection pkg-config jq

Sources/GLib/GLib.docc/Package.md

@@ -0,0 +1,36 @@
+# SwiftGLib
+
+A Swift wrapper around glib-2.x that is largely auto-generated from gobject-introspection.
+For up to date (auto-generated) reference documentation, see
+[https://rhx.github.io/SwiftGLib/](https://rhx.github.io/SwiftGLib/).
+
+## Overview
+
+[SwiftGLib](https://github.com/rhx/SwiftGLib/) allows you to use the low-level GLib library
+directly from Swift without having to resort to using the low-level C interface.
+GLib has been in development for many years and is used by numerous open source
+programs and libraries including [Gtk](https://rhx.github.io/SwiftGtk/).
+GLib is particularly useful for organising low-level data by providing abstractions
+for data structures, containers, and collections that can directly be used by C code
+as well as Swift.
+
+## Topics
+
+### Essentials
+
+- <doc:GettingStarted>
+- <doc:Usage>
+- <doc:Documentation>
+
+### Tutorial
+
+- <doc:Tutorial>
+
+### Troubleshooting
+
+- <doc:Troubleshooting>
+
+### Building and Testing SwiftGLib
+
+- <doc:Building>
+

Sources/GLib/GLib.docc/Troubleshooting.md

@@ -0,0 +1,49 @@
+# Troubleshooting
+
+This section shows some common errors you might encounter and how to fix them.
+
+## FFI Module Errors
+
+On some versions of macOS, when Xcode is installed,
+there is a conflict between the FFI library module
+available through Xcode and the command line tools.
+This typically results in an error such as
+
+    /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX14.2.sdk/usr/include/ffi/module.modulemap:1:8: error: redefinition of module 'FFI'
+    module FFI [system] {
+           ^
+    /Library/Developer/CommandLineTools/SDKs/MacOSX13.sdk/usr/include/ffi/module.modulemap:1:8: note: previously defined here
+    module FFI [system] [extern_c] {
+           ^
+    error: fatalError
+
+A way to resolve this is to remove the Command Line Tools.
+Alternatively, you can temporarily rename the CommandLineTools folder, i.e.
+
+    sudo mv /Library/Developer/CommandLineTools{,.orig}
+
+Later you can move the folder back:
+
+    sudo mv /Library/Developer/CommandLineTools{.orig,}
+
+## Missing `.gir` Files
+
+If you get an error such as
+
+	Girs located at
+	Cannot open '/GLib-2.0.gir': No such file or directory
+
+Make sure that you have the relevant `gobject-introspection` packages installed (as per the Pre-requisites section), including their `.gir` and `.pc` files.
+
+## Old Swift toolchain or Xcode
+If, when you run `swift build`, you get a `Segmentation fault (core dumped)` or circular dependency error such as
+
+	warning: circular dependency detected while parsing pangocairo: harfbuzz -> freetype2 -> harfbuzz
+
+this probably means that your Swift toolchain is too old, particularly on Linux.
+Make sure the latest toolchain is the one that is found when you run the Swift compiler (see above).
+
+  If you get an older version, make sure that the right version of the swift compiler is found first in your `PATH`.  On macOS, use xcode-select to select and install the latest version, e.g.:
+
+	sudo xcode-select -s /Applications/Xcode.app
+	xcode-select --install

Sources/GLib/GLib.docc/Tutorial.md

@@ -0,0 +1,189 @@
+# Using GLib with Swift
+
+This tutorial shows how to use GLib with Swift.
+This is particularly useful if you want to interact
+with libraries written in C or other languages that use GLib.
+
+
+## What is GLib?
+
+[GLib](https://docs.gtk.org/glib/) is a low-level,
+general-purpose software library that provides a set of
+useful data types, string utilities, filesystem abstractions,
+a mainloop abstraction, and similar tools for developing
+libraries and applications in different programming languages.
+GLIb is mainly used for creating and interacting with
+low-level data structures and supports features such as
+event-driven programming, memory management, and data
+type management.
+GLib is part of the GNOME project, but works with different
+Operating Systems, including Linux and macOS.
+
+
+## Swift Bindings
+
+The Swift language bindings have been generated using
+the `.gir` files from
+[GObject Introspection](https://gi.readthedocs.io/en/latest/),
+allowing a more "swifty" use of the library than using it
+through the low-level C interface.
+Particularly the collection interfaces, such as
+[singly](https://rhx.github.io/SwiftGLib/GLib/documentation/glib/typedslist) and
+[doubly-linked lists](https://rhx.github.io/SwiftGLib/GLib/documentation/glib/typedlist)
+allow to use templated Swift data types rather than raw
+pointers.
+
+
+## Prerequisites
+
+To get the most out of this tutorial, you should be
+generally familiar with Linux, macOS, or other UNIX-like
+environments and know how to use a command-line shell
+such as [bash](https://www.gnu.org/software/bash/) or
+[zsh](https://www.zsh.org/).
+
+You will need a
+[working Swift compiler](https://www.swift.org/getting-started/cli-swiftpm/),
+either by
+[installing Xcode](https://developer.apple.com/support/xcode/)
+if you are running macOS, or
+by [installing Swift](https://www.swift.org/install/)
+directly for your Operating System.
+
+You also need to install the GLib development libraries
+for your system.
+
+### Installing GLib on Linux
+
+Most modern Linux distributions come with the GLib runtime
+preinstalled, but you will need to install the headers
+necessary for development.
+This can be done using the package manager for your system.
+For example, on Ubuntu or other Debian-based systems,
+you can use the [apt](https://wiki.debian.org/Apt) package
+manager using the following commands:
+
+    sudo apt update
+    sudo apt install libglib2.0-dev glib-networking gobject-introspection libgirepository1.0-dev libxml2-dev jq
+
+Depending on your Linux distributions, the names of the
+packages and package management tools will vary.
+You should be able to find this in the documentation for
+your Linux distribution.
+
+> Tip: Some more examples can also be found in the
+[README](https://github.com/rhx/SwiftGLib/blob/main/README.md).
+
+### Installing GLib on macOS
+
+For macOS, there are multiple package management tools
+that you can use.
+[HomeBrew](http://brew.sh/) is one example.
+After you have installed HomeBrew, you can install
+GLib using:
+
+    brew update
+    brew install glib glib-networking gobject-introspection pkg-config jq
+
+
+## Compiling SwiftGLib programs
+
+The easiest way to compile programs and libraries using
+SwiftGLib is through projects using the
+[Swift Package Manager](https://swift.org/package-manager/).
+Here is an example for a simple program that uses a
+[type list](https://rhx.github.io/SwiftGLib/GLib/documentation/glib/typedlist).
+First, create a directory (folder) for your project, then
+create the project inside the folder:
+
+    mkdir swift-glist
+    cd swift-glist
+    swift package init --type=executable
+
+This will create a simple "Hello World" executable that
+you can test using `swift run` -- the program will run
+and print "Hello world".
+If you look at the files generated by `swift package init`,
+you will find a file named `Package.swift` that represents
+the project and its compilation targets.
+Overall, if you run
+
+    find * -type f
+
+you should see two files, the aforementioned `Package.swift`
+and a `main.swift` in `Sources/swift-glist`:
+
+    Package.swift
+    Sources/swift-glist/main.swift
+
+> Warning: Some versions of the Swift Package manager create
+a flat structure when using `swift package init` that puts
+the `main.swift` directly in the `Sources` folder.
+This will cause the Swift compiler to exit with an error if
+you try to use `swift run`.
+
+Such a faulty structure that places your `main.swift`
+directly in the `Sources` folder would look like this:
+
+    Package.swift
+    Sources/main.swift
+
+In this case, your program won't compile or run.
+To fix this, you need to move the `main.swift` file
+into a `swift-glist` subfolder:
+
+    mkdir Sources/swift-glist
+    mv Sources/main.swift Sources/swift-glist/
+
+Now you should be able to build your project.
+
+Let us now change the `Package.swift` file so that it
+reads:
+
+```Swift
+// swift-tools-version: 5.7
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-glist",
+    dependencies: [
+        .package(url: "https://github.com/rhx/gir2swift.git", branch: "main"),
+        .package(url: "https://github.com/rhx/SwiftGLib.git", branch: "main"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "swift-glist",
+            dependencies: [
+                .product(name: "GLib", package: "SwiftGLib"),
+            ]
+        ),
+    ]
+)
+```
+This will add the relevant dependencies for SwiftGLib
+to the project.  We can now change the code in our
+`Sources/swift-glist/main.swift` so that it reads:
+```Swift
+import GLib
+
+let list: TypedList = ["Hello", "world"]
+
+print(list.length())  // Prints: 2
+
+list.forEach { element in
+    print(element)    // Prints: "hello" and "world"
+}
+```
+Compile and run the code using:
+
+    swift run
+
+After some compiler output (and potentially
+some warnings that you can ignore), you should get the
+following output:
+
+    2
+    Hello
+    world
+

Sources/GLib/GLib.docc/Usage.md

@@ -0,0 +1,32 @@
+# Usage
+
+Typically, you embed this package into your own project
+using the [Swift Package Manager](https://swift.org/package-manager/).
+
+After installing the prerequisites (see <doc:GettingStarted>),
+add this package as a dependency to your `Package.swift` file.
+
+E.g.:
+
+```swift
+// swift-tools-version: 5.9
+
+import PackageDescription
+
+let package = Package(
+    name: "MyPackage",
+    dependencies: [
+        .package(url: "https://github.com/rhx/gir2swift.git", branch: "main"),
+        .package(url: "https://github.com/rhx/SwiftGLib.git", branch: "main"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "MyPackage",
+            dependencies: [
+                .product(name: "GLib", package: "SwiftGLib"),
+            ]
+        ),
+    ]
+)
+```
+