docs: Add `PACKAGING.md` instructions by mati865 · Pull Request #1342 · wild-linker/wild

mati865 · 2025-11-25T20:56:02Z

TODO: replace this description before merging

Likely needs corrections and changes. Don't be afraid to post your ideas and thoughts.

I'm planning to leave it open for at least a week, but we can prolong that if needed.

cc @davidlattimore @marxin @lapla-cogito

davidlattimore

Thanks for writing this up!

It could be good to also invite packagers to file an issue or otherwise reach out if they have any pain points that we might be able to help with.

davidlattimore · 2025-11-25T22:27:45Z

+
+To test built binary, you can use `cargo test`, preferably with the same configuration as the build
+to avoid rebuilding.
+The testsuite is configured with `test-config.toml` file (default values are used if absent).


Are these intended as separate paragraphs? Markdown will merge them together unless there's a blank line between them.

Intellij by default splits sentences into new lines, I can disable this if you want.
I'm aware of how Markdown works, but maybe I should do splitting here and there? I'm terrible at writing documents...

Ah, that makes sense then, so they're not intended to be separate paragraphs. Splitting sentences onto new lines seems odd to me, but I don't really mind. I'm sure now that I know what's happening, I'll get use to it.

I'll just disable the sentence splitting, set splitting after 100th character and reflow it.

Turns out I just enabled the wrong setting in the options 🤦🏻‍♂️
Reflowed the text.

davidlattimore · 2025-11-25T22:35:20Z

+
+This project uses Cargo as its build system.
+Wild's official artifacts are built using with `--profile dist` that enables compiler's internal
+ThinLTO and strips the binaries.


It's funny. I'd thought for some time that our setting of lto = "thin" was redundant because I thought that was the default for optimised builds, however upon reading the docs again, I think I was mistaken. It sounds like there's one more LTO option than I had realised. Seems like the choices for LTO are none, thin-crate-local, thin-global, fat or linker-plugin-lto. I hadn't realised the distinction between thin-crate-local and thin-global (my names, not official names).

Ah, that makes sense then, so they're not intended to be separate paragraphs. Splitting sentences onto new lines seems odd to me, but I don't really mind. I'm sure now that I know what's happening, I'll get use to it.

Yeah, you can look at https://nnethercote.github.io/perf-book/build-configuration.html#link-time-optimization for the terminology.

In C/C++ world, linker is also involved in ThinLTO in some manner (LLD has some thinlto-* argsand it works only with Gold and LLD). Also, everyone has different idea what each LTO level means to add to the confusion: https://wiki.gentoo.org/wiki/LTO#Terminology

I'm not sure if my "compiler's internal ThinLTO" is correct. I mean, the linker is not involved in LTO at all, unlike in Clang's case.

davidlattimore

Thanks! Looks good to me

davidlattimore · 2025-11-26T20:37:56Z

+
+## Binaries
+
+This repository consists of Wild linker and linker-diff binaries. We recommend providing `wild`


Insert "the" before "Wild"?

Coming from a language without the concept of "the", I doubt I'll ever get it right. Don't hesitate to point it out more.

lapla-cogito · 2025-11-27T00:16:55Z

+## Testing
+
+To test built binary, you can use `cargo test`, preferably with the same configuration as the build
+to avoid rebuilding. The testsuite is configured with `test-config.toml` file (default values are


Since packaging contributors may not always be familiar with Wild, I think it would be more helpful if a note was added indicating that detailed information about each test option can be found at here.

lapla-cogito · 2025-11-27T00:30:37Z

+To test built binary, you can use `cargo test`, preferably with the same configuration as the build
+to avoid rebuilding. The testsuite is configured with `test-config.toml` file (default values are
+used if absent). To tweak the configuration, you can copy `test-config.toml.example` to
+`test-config.toml` and edit it to your liking. Just be careful with `run_all_diffs` option, it's


(This may not directly relate to this section, but) clang-format tests are currently only able to be ignored by setting the WILD_TEST_IGNORE_FORMAT environment variable. This is mentioned in here, but might be easily overlooked at first glance. Since these tests could potentially fail depending on the clang version in the packaging environment, it might be worth considering whether clang formatting checks could be included in run_all_diffs (though this would likely need discussion), or at least explicitly mentioning the existence of this environment variable in the documentation.

Good idea, we should make it more straightforward, I don't have preference for a particular solution.

I believe we should determine how to handle clang-format diffs before the next release, since packaging typically occurs for already-released versions. Unless there are strong objections, I tend to include clang-format diffs in the run_all_diffs scope in a separate PR. The description in test-config.toml.sample would need to be updated in that case anyway, and I can take care of the whole thing.

For packaging, we generally don't want to run any kind of lint tests (and clang-format would count as one). If setting the env var is required for that, the doc should mention it.

I agree that controlling the clang-format test from test-config.toml makes sense. I'd perhaps make it a separate option, but I don't feel strongly.

Relatedly, I'm wondering if we should add a profile option to the test config which affects defaults. Possibly values might be "developer" or "unspecified", with "unspecified" being what you get if you don't have a config and so would apply to package builders. If we add new options that we think active developers should have on by default, we can set them in that profile's defaults. Not sure if we want to do that or not - just an idea.

Added info about the environment variable. While configuring it via test-config.toml would be better, it's outside of this PR scope.

lapla-cogito

Thanks! Looks good to me.

docs: Add PACKAGING.md instructions

cab3798

davidlattimore reviewed Nov 25, 2025

View reviewed changes

mati865 added 4 commits November 26, 2025 12:36

reflow

64a96d3

reword a few chunks

4898e8a

Add issues section

35c4264

s/artifacts/releases

1d3e55b

davidlattimore approved these changes Nov 26, 2025

View reviewed changes

lapla-cogito reviewed Nov 27, 2025

View reviewed changes

mati865 added 3 commits November 28, 2025 12:49

add "the"

60e9f96

link CONTRIBUTING.md

8558483

Mention WILD_TEST_IGNORE_FORMAT

1bd84fc

mati865 marked this pull request as ready for review December 4, 2025 13:08

lapla-cogito approved these changes Dec 7, 2025

View reviewed changes

reflow a sentence

509bd07

mati865 merged commit 0d8fd90 into wild-linker:main Dec 7, 2025
20 checks passed

mati865 deleted the push-trnvzsvuknmu branch December 7, 2025 14:04


		## Binaries

		This repository consists of Wild linker and linker-diff binaries. We recommend providing `wild`

Uh oh!

Uh oh!

Conversation

mati865 commented Nov 25, 2025

Uh oh!

davidlattimore left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidlattimore left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lapla-cogito left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants