From 8f19eb9ae1b03b77cb7bdd0c9de792926bb8eca0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20R=C3=B8nne=20Petersen?= Date: Tue, 2 Jul 2024 09:29:54 +0200 Subject: [PATCH] Add README.md and some Vezel repository scaffolding. --- .editorconfig | 25 ++++++++++ .gitattributes | 7 +++ .github/CODEOWNERS | 1 + .github/CONTRIBUTING.md | 12 +++++ .github/SECURITY.md | 7 +++ .github/dependabot.yml | 21 ++++++++ .markdownlint.json | 103 ++++++++++++++++++++++++++++++++++++++++ .netconfig | 15 ++++++ .vscode/extensions.json | 14 ++++++ .vscode/settings.json | 6 +++ README.md | 97 +++++++++++++++++++++++++++++++++++++ RELEASE.md | 36 ++++++++++++++ dotnet-tools.json | 18 +++++++ global.json | 8 ++++ 14 files changed, 370 insertions(+) create mode 100644 .editorconfig create mode 100644 .gitattributes create mode 100644 .github/CODEOWNERS create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/SECURITY.md create mode 100644 .github/dependabot.yml create mode 100644 .markdownlint.json create mode 100644 .netconfig create mode 100644 .vscode/extensions.json create mode 100644 .vscode/settings.json create mode 100644 README.md create mode 100644 RELEASE.md create mode 100644 dotnet-tools.json create mode 100644 global.json diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..357fb0bcc --- /dev/null +++ b/.editorconfig @@ -0,0 +1,25 @@ +root = true + +[*] +charset = utf-8 +indent_size = 4 +indent_style = space +insert_final_newline = true +max_line_length = 120 +tab_width = 4 +trim_trailing_whitespace = true + +[*.json] +indent_size = 2 + +[*.jsonc] +indent_size = 2 + +[*.vsconfig] +indent_size = 2 + +[*.yaml] +indent_size = 2 + +[*.yml] +indent_size = 2 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..32eaedaca --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +* text +*.verified.* text eol=lf +*.ico binary +*.pdf binary +*.png binary +*.zig eol=lf +*.zon eol=lf diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..3233e4f3b --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @vezel-dev/graf-maintainers diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..88f940edd --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,12 @@ +# Contributing + +This repository is a fork that only makes build system changes and provides Zig +bindings. As such, most issues and pull requests should be directed +[upstream](https://github.com/libffi/libffi). That said, if your issue or pull +request is related to our fork's changes, then please see +[our organization contribution guide](https://github.com/vezel-dev/.github/blob/master/CONTRIBUTING.md). + +Please note that, if you send a pull request and it is merged, it is quite +likely that the record of your contribution will be lost, even though the change +itself is kept. This happens because we rebase the `master` branch periodically +and try to keep the number of commits on top of upstream to a minimum. diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 000000000..7e3b50536 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,7 @@ +# Security + +This repository is a fork that only makes build system changes and provides Zig +bindings. As such, most security issues should be directed +[upstream](https://github.com/libffi/libffi). That said, if you wish to report a +security issue that is related to our fork's changes, then please see +[our organization security policy](https://github.com/vezel-dev/.github/security/policy). diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..f1cec6fe2 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,21 @@ +# yaml-language-server: $schema=https://json.schemastore.org/dependabot-2.0.json +version: 2 +updates: + - package-ecosystem: dotnet-sdk + directories: + - / + schedule: + interval: daily + timezone: Europe/Copenhagen + time: "12:00" + open-pull-requests-limit: 25 + labels: [] + - package-ecosystem: nuget + directories: + - / + schedule: + interval: daily + timezone: Europe/Copenhagen + time: "12:00" + open-pull-requests-limit: 25 + labels: [] diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 000000000..b3840b816 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,103 @@ +{ + "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json", + "default": true, + "MD001": true, + "MD003": { + "style": "atx" + }, + "MD004": { + "style": "asterisk" + }, + "MD005": true, + "MD007": { + "start_indented": false, + "start_indent": 4, + "indent": 4 + }, + "MD009": { + "br_spaces": 0, + "strict": true + }, + "MD010": { + "spaces_per_tab": 4 + }, + "MD011": true, + "MD012": true, + "MD013": { + "code_blocks": false, + "headings": false, + "tables": false + }, + "MD014": true, + "MD018": true, + "MD019": true, + "MD020": true, + "MD021": true, + "MD022": true, + "MD023": true, + "MD024": true, + "MD025": true, + "MD026": { + "punctuation": "!,.:;?" + }, + "MD027": true, + "MD028": true, + "MD029": { + "style": "ordered" + }, + "MD030": true, + "MD031": true, + "MD032": true, + "MD033": { + "allowed_elements": [ + "div", + "img", + "p", + "strong" + ] + }, + "MD034": true, + "MD035": { + "style": "--------------------------------------------------------------------------------" + }, + "MD036": { + "punctuation": "!,.:;?" + }, + "MD037": true, + "MD038": true, + "MD039": true, + "MD040": { + "language_only": true + }, + "MD041": true, + "MD042": true, + "MD043": false, + "MD044": true, + "MD045": true, + "MD046": { + "style": "fenced" + }, + "MD047": true, + "MD048": { + "style": "backtick" + }, + "MD049": { + "style": "asterisk" + }, + "MD050": { + "style": "asterisk" + }, + "MD051": true, + "MD052": true, + "MD053": { + "ignored_definitions": [] + }, + "MD054": { + "url_inline": false + }, + "MD055": { + "style": "leading_and_trailing" + }, + "MD056": true, + "MD058": true +} diff --git a/.netconfig b/.netconfig new file mode 100644 index 000000000..87fff7adb --- /dev/null +++ b/.netconfig @@ -0,0 +1,15 @@ +[file ".editorconfig"] + url = https://github.com/vezel-dev/.github/blob/master/syn/.editorconfig + sha = 25cfbb6a508a9fcf8444ef283ddfe7b2e5121bca + etag = df90691e6bc4d301e82e508fca55eed234028a335c3615cf916db00cb4a053f1 + weak +[file ".gitattributes"] + url = https://github.com/vezel-dev/.github/blob/master/syn/.gitattributes + sha = 0ff05334db6d820dd16428e1aad477ed83ca10ef + etag = 0a6a1f6373760bc1c03e09e1efeeb77109705f11b159afd759e11550b45ee950 + weak +[file ".markdownlint.json"] + url = https://github.com/vezel-dev/.github/blob/master/syn/.markdownlint.json + sha = 72ec690564533b1ad756f452be9b3ea5075ad124 + etag = 6d74ad50782defb281b210a627cae9d255cbb419cdc705b0571f1653dbe02300 + weak diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 000000000..315482040 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,14 @@ +{ + "recommendations": [ + "chdsbd.github-code-owners", + "codezombiech.gitignore", + "davidanson.vscode-markdownlint", + "editorconfig.editorconfig", + "github.vscode-github-actions", + "github.vscode-pull-request-github", + "llvm-vs-code-extensions.vscode-clangd", + "redhat.vscode-yaml", + "yy0931.gitconfig-lsp", + "ziglang.vscode-zig" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..bbe02d0aa --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,6 @@ +{ + "files.exclude": { + ".zig-cache": true, + "zig-out": true + } +} diff --git a/README.md b/README.md new file mode 100644 index 000000000..da77d64cc --- /dev/null +++ b/README.md @@ -0,0 +1,97 @@ +# Vezel libffi Fork + +This is a friendly fork of [libffi](https://sourceware.org/libffi). The notable +changes made in this fork are the additions of a [Zig](https://ziglang.org) +build script, making it easy to integrate libffi into Zig projects using the Zig +package manager, and a set of idiomatic Zig bindings for libffi's main API. +Additionally, to reduce the package download size, we have removed a large +number of files that are unnecessary when using libffi in a Zig project. +Importantly, **all library source code is identical to upstream**, so in terms +of API/ABI compatibility, using this fork is no different from linking to a +system libffi package. + +## Usage + +The minimum Zig version supported by this project can be found in the +`minimum_zig_version` field of the [`build.zig.zon`](build.zig.zon) file. We +generally try to track the latest release of Zig. But do note that the `master` +branch may sometimes contain code that only works with a `master` build of Zig. + +Please note that the `master` branch is rebased on top of upstream periodically. +**You should use a release tag rather than `master`.** For example: + +```bash +zig fetch --save=ffi https://github.com/vezel-dev/libffi/archive/vX.Y.Z-B.tar.gz +# Or, to use Git: +zig fetch --save=ffi git+https://github.com/vezel-dev/libffi.git#vX.Y.Z-B +``` + +(You can find the latest version on the +[releases page](https://github.com/vezel-dev/libffi/releases).) + +Consume the library in your `build.zig`: + +```zig +const ffi = b.dependency("ffi", .{ + .target = target, + .optimize = optimize, +}); + +exe.root_module.addImport("ffi", ffi.module("ffi")); + +if (b.systemIntegrationOption("ffi", .{})) { + exe.linkSystemLibrary("ffi"); +} else { + exe.linkLibrary(ffi.artifact("ffi")); +} +``` + +You can now use the Zig bindings in your code: + +```zig +const builtin = @import("builtin"); +const std = @import("std"); +const stdio = @cImport(@cInclude("stdio.h")); +const ffi = @import("ffi"); + +pub fn main() !void { + std.debug.print("Calling C puts() on {s}.\n", .{builtin.cpu.arch.genericName()}); + + var func: ffi.Function = undefined; + var params = [_]*ffi.Type{ + ffi.types.pointer, + }; + + try func.prepare(ffi.Abi.default, params.len, params[0..params.len], ffi.types.sint32); + + var result: ffi.uarg = undefined; + var args = [params.len]*anyopaque{ + @ptrCast(@constCast(&"Hello World")), + }; + + func.call(&stdio.puts, args[0..args.len], &result); + + if (result == stdio.EOF) return error.IOError; +} +``` + +And finally: + +```console +$ zig build run +Calling C puts() on x86. +Hello World +``` + +Cross-compilation works too: + +```console +$ zig build run -fqemu -Dtarget=aarch64-linux +Calling C puts() on aarch64. +Hello World +``` + +## License + +This project is licensed under the terms found in [`LICENSE`](LICENSE); this +file is unchanged from upstream. diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 000000000..7969f866f --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,36 @@ +# Release + +Every upstream release should have a corresponding release branch and tag here. +The branch should be named `release/vX.Y.Z`; that is, unlike normal Vezel +convention, even a patch release gets a unique branch. The tag should be named +`vX.Y.Z-B`, where B represents our one-based fork version. B is incremented +whenever we make fixes to the Zig build script or bindings within the same +upstream release cycle, and is reset for any new X/Y/Z combination. + +This is the procedure for creating a new release from an upstream release: + +1. Run `git checkout -b release/vX.Y.Z vX.Y.Z` to create and switch to the new + release branch. +2. Cherry-pick our fork's commit range from `master` and resolve any conflicts + in the process. +3. Adjust the libffi version in [`build.zig`](build.zig) and + [`build.zig.zon`](build.zig.zon), and then commit the changes. +4. Make sure `zig build` works. Try cross-compiling for any targets that had + changes in the upstream release. +5. Push the release branch. +6. Run `git tag vX.Y.Z-B -m vX.Y.Z-B -s` to create and sign a release tag, then + push it. +7. Go to the [releases page](https://github.com/vezel-dev/libffi/releases) to + create a release from the new tag. The release notes should just be a link to + the upstream release, such as + [this one](https://github.com/libffi/libffi/releases/tag/v3.4.6). + +(Obviously, step 2 will be easier if `master` is not lagging behind upstream.) + +The procedure for creating a release that only includes fixes to the Zig build +script or bindings is simpler: Just commit the fix to the release branch and +then proceed from step 4. Remember to increment the B value! + +If something goes wrong, you can run `git tag -d vX.Y.Z-B` and +`git push origin :vX.Y.Z-B` to delete the tag until you resolve the issue(s), +and then repeat whichever steps are necessary. diff --git a/dotnet-tools.json b/dotnet-tools.json new file mode 100644 index 000000000..c780424a4 --- /dev/null +++ b/dotnet-tools.json @@ -0,0 +1,18 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "dotnet-config": { + "version": "1.2.0", + "commands": [ + "dotnet-config" + ] + }, + "dotnet-file": { + "version": "1.7.1", + "commands": [ + "dotnet-file" + ] + } + } +} diff --git a/global.json b/global.json new file mode 100644 index 000000000..b04289504 --- /dev/null +++ b/global.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json.schemastore.org/global.json", + "sdk": { + "version": "9.0.100", + "rollForward": "disable", + "allowPrelease": false + } +}