# libui-ng-sys

[![crates.io](https://img.shields.io/crates/v/libui-ng-sys)](https://crates.io/crates/libui-ng-sys)
[![docs](https://docs.rs/libui-ng-sys/badge.svg)](https://docs.rs/libui-ng-sys)
[![MPL 2.0 licensed](https://img.shields.io/github/license/norepimorphism/libui-ng-sys)](./LICENSE)

Rust bindings to [*libui-ng*](https://github.com/libui-ng/libui-ng).

## Usage

Add the *libui-ng-sys* crate from [crates.io](https://crates.io) to your *Cargo.toml*:

```toml
[dependencies]
libui-ng-sys = "0.7"
```

When built, the *libui-ng-sys* build script emits linker flags to the compiler that link *libui-ng* to your build product, whether that be an executable or another library.

### The `probe-system-libui` Feature

By default, *libui-ng-sys* searches for an existing installation of *libui-ng* to link dynamically with. If *libui-ng* is not installed, it is built from source and linked statically. This behavior can be modified by disabling the `probe-system-libui` feature, which causes *libui-ng* to always be built from source:

```toml
[dependencies.libui-ng-sys]
default-features = false
```

### Build Systems

By default, *libui-ng-sys* vendors the [Ninja build system](https://ninja-build.org), builds Ninja, and then uses Ninja to build *libui-ng*. If you prefer a different build system, *libui-ng-sys* offers support for MSVC and Xcode under the `build-with-msvc` and `build-with-xcode` features, respectively. You can enable them in *Cargo.toml* like this:

```toml
[dependencies.libui-ng-sys]
features = ["build-with-msvc"] # Or "build-with-xcode"!
```

## Build Requirements

If *libui-ng* is to be built from source, the host environment must provide a working C compiler, linker, and Python installation (≥ v3.7) at a minimum.

Additional per-platform build requirements are listed in the below sections.

### Linux Build Requirements

GTK3 (≥ v3.10.0) is required. GTK4 is not currently supported.

GTK can be installed on APT-based systems with this command:

```shell
apt-get install libgtk-3-dev
```

### Windows Build Requirements

A Windows 10 or 11 SDK is required.

SDKs may be acquired from the [Visual Studio Installer](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022).

## Common Errors on Windows

If building *libui-ng* from source, all compiler components must be accessible from your `$PATH`. The easiest way to do this is to build *libui-ng-sys* from a Developer Command Prompt or Developer PowerShell. If *libui-ng-sys* suspects that some compiler components are missing, it will issue a warning to use a developer shell.

But, be careful to open the correct developer shell! On 64-bit Windows, the one containing "x64" is what you want. It might look like this:

> x64 Native Tools Command Prompt for VS 2022

If *libui-ng-sys* is compiled with the wrong toolchain, *libui-ng* will fail to link, and you will receive cryptic linker errors like these:

```text
basic.basic.6dc1d4cc-cgu.0.rcgu.o : error LNK2019: unresolved external symbol uiInit referenced in function _ZN5basic4main17h947588e76d3f9c99E
```

## Vendored Dependencies

*libui-ng-sys* vendors *libui-ng*, Meson, and Ninja as Git submodules. The latest commit hashes and nominal versions of these submodules are documented below for each release of *libui-ng-sys*.

### 0.7.0

| Dependency | Commit Hash                                | Nominal Version |
| ---------- | ------------------------------------------ | --------------- |
| *libui-ng* | `8c82e737eea2f8ab3667e227142abd2fd221f038` | alpha4.1-697    |
| Meson      | `09ad4e28f1a59ab3d87de6f36540a108e836cfe5` | 0.62.0-112      |
| Ninja      | `25cdbae0ee1270a5c8dd6ba67696e29ad8076919` | 1.11.0^2~2      |

### 0.2.0–0.6.0

| Dependency | Commit Hash                                | Nominal Version |
| ---------- | ------------------------------------------ | --------------- |
| *libui-ng* | `42641e3d6bfb2c49ca4cc3b03d8ae277d9841a5d` | alpha4.1-479    |
| Meson      | `09ad4e28f1a59ab3d87de6f36540a108e836cfe5` | 0.62.0-112      |
| Ninja      | `25cdbae0ee1270a5c8dd6ba67696e29ad8076919` | 1.11.0^2~2      |

### 0.1.0

| Dependency | Commit Hash                                | Nominal Version |
| ---------- | ------------------------------------------ | --------------- |
| *libui-ng* | `42641e3d6bfb2c49ca4cc3b03d8ae277d9841a5d` | alpha4.1-479    |

## Acknowledgements

*libui-ng-sys*, and its sister crate [*boing*](https://github.com/norepimorphism/boing), are the *-ng* analogues to [@NoraCodes](https://github.com/NoraCodes)' [*libui-rs*](https://github.com/rust-native-ui/libui-rs), which predated these crates by at least two years. Though it shares no common code with *libui-ng-sys* or *boing* and was developed separately, *libui-rs* was nonetheless inspiration for these crates, and I recommend checking out *libui-rs* as well as Nora's other work.

I should also thank [@cody271](https://github.com/cody271) and [@szanni](https://github.com/szanni) for their help and contributions to *libui-ng*.