add-conan-recipe
Skill766 starsChanged 36 days agoApache-2.0View on GitHub
Add a Conan recipe for a third-party dependency under recipes/ and publish it to the endstone/conan Cloudsmith remote. Use when the user wants to package a C/C++ library that isn't on conancenter (or needs project-specific patches) so endstone can consume it via conan rather than FetchContent. Examples - "add a recipe for libwhatever", "package zydis on cloudsmith", "replace the X FetchContent with a conan dep".
- Deletes or force-pushes
- Installs packages
In this repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- build-ida-dbSkill
- bump-bdsSkill
- fix-issueSkill
- locate-functionSkill
- reconcile-headersSkill
- releaseSkill
- update-signaturesSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 9 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Before scaffolding, you need:
- Very specific: line 21
Source tarball URL: Prefer the GitHub release archive (https://github.com/<owner>/<repo>/archive/refs/tags/v<version>.tar.gz).
- Distinctive: line 23
If upstream uses submodules, you'll need a separate URL per submodule plus its pinned commit SHA (see Step 2.b).
- Very specific: line 29
Whether the user wants to upload after local validation: Default: recipe-only upload to endstone remote.
- Very specific: line 32
If any of these are unclear, ask once with AskUserQuestion before scaffolding.
- Distinctive: line 39
Create the folder tree:
- Very specific: line 118
Use the funchook recipe (recipes/funchook/all/conanfile.py) as the template.
- Very specific: line 135
If there are patches, call apply_conandata_patches(self) after get().
- Very specific: line 149
If upstream's CMakeLists downloads a dep at configure time (e.g.
- Distinctive: line 172
STOP: if you can't think of a meaningful end-to-end test.
- Distinctive: line 179
Run from project root with cmake on PATH:
- Distinctive: line 186
If the recipe has options, test the non-default value too:
- Very specific: line 201
Test executable crashes with no useful output → ABI mismatch between separate builds of the same lib (classic when patching a find_package …
- Very specific: line 225
After the run, delete the throwaway cache: rm -rf .linux-home.
- Distinctive: line 234
STOP: before uploading. Confirm with the user the upload scope:
- Distinctive: line 276
If the goal was to replace a FetchContent or to add a new dep, then:
- Very specific: line 278
Add self.requires("<name>/<version>") to the project root conanfile.py.
- Very specific: line 280
Add find_package(<name> CONFIG REQUIRED) in the consuming src/.../CMakeLists.txt (typically src/endstone/runtime/CMakeLists.txt for …
- Very specific: line 283
Update target_link_libraries(...) to use <name>::<name> (most likely already named this way if you replaced a FetchContent alias).
- Very specific: line 285
Delete the old third_party/<name>/ folder and its add_subdirectory(<name>) line in third_party/CMakeLists.txt.
- Distinctive: line 310
Commit style matches the repo's conventional-commit history:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add a Conan recipe
This skill scaffolds a Conan 2.x recipe under recipes/<name>/all/, validates
it on Windows and Linux, and publishes it (recipe-only by default) to the
endstone Cloudsmith remote. The layout mirrors conan-center-index so the
recipe could be upstreamed later with minimal change.
Execute steps in order. STOP points wait for user input.
Inputs to collect up front
Before scaffolding, you need:
- Package name (lowercase, kebab-case) and version (e.g.
funchook/1.1.3). - Source tarball URL. Prefer the GitHub release archive
(
https://github.com/<owner>/<repo>/archive/refs/tags/v<version>.tar.gz). If upstream uses submodules, you'll need a separate URL per submodule plus its pinned commit SHA (see Step 2.b). - Build system (CMake is the only one this skill handles cleanly; if it's autotools/meson/Make, stop and tell the user this skill assumes CMake — they may want to extend it).
- License SPDX identifier — read the upstream LICENSE file.
- Whether the user wants to upload after local validation. Default:
recipe-only upload to
endstoneremote.
If any of these are unclear, ask once with AskUserQuestion before
scaffolding.
Step 1 - directory layout
Create the folder tree:
recipes/<name>/
├── config.yml
└── all/
├── conandata.yml
├── conanfile.py
├── patches/ # optional, only if upstream needs patching
│ └── <version>-<short>.patch
└── test_package/
├── CMakeLists.txt
├── conanfile.py
└── test_package.<c|cpp>config.yml maps versions to their recipe folder:
versions:
"<version>":
folder: allStep 2 - sources and sha256
2.a Single tarball
Download the tarball to a scratch location and hash it:
mkdir -p build/sha-tmp
curl -sL -o build/sha-tmp/src.tar.gz "<URL>"
sha256sum build/sha-tmp/src.tar.gzWrite recipes/<name>/all/conandata.yml:
sources:
"<version>":
url: "<URL>"
sha256: "<HASH>"2.b Tarball + submodule(s)
GitHub release archives don't include git submodules. If git ls-tree HEAD
<submodule-path> on the upstream repo shows a commit SHA, download the
submodule's archive at that exact commit:
https://github.com/<owner>/<repo>/archive/<sha>.tar.gzHash it the same way. The conandata.yml then names each source so the
recipe's source() can unpack them to the right relative paths:
sources:
"<version>":
main:
url: "..."
sha256: "..."
# one entry per submodule, named after the submodule's path
<submodule>:
url: "..."
sha256: "..."In source(), use get(..., destination=os.path.join(self.source_folder,
"<submodule>")) to land it where upstream's CMakeLists expects.
Step 3 - scaffold conanfile.py
Use the funchook recipe (recipes/funchook/all/conanfile.py) as the
template. Key elements that almost always apply:
name,description,license,url=<our project URL>,homepage=<upstream URL>,topics,package_type = "library".exports_sources = "patches/*"if you added patches.- Settings:
os, arch, compiler, build_type. Options: at minimumsharedandfPIC(deletefPICon Windows inconfig_options). Add upstream feature options as needed. configure():rm_safe("compiler.cppstd")/rm_safe("compiler.libcxx")if it's a pure C library — otherwisepackage_idcarries spurious C++ fields.requirements(): only conan deps. Anything bundled in the upstream source (submodules, downloaded-at-configure) should be handled insource()/package(), notrequires.validate(): reject unsupported arch/OS withConanInvalidConfiguration.source():get(self, **self.conan_data["sources"][self.version], ...). If there are patches, callapply_conandata_patches(self)afterget().layout():cmake_layout(self, src_folder="src").generate():CMakeToolchain+CMakeDeps. Set the upstream's cache variables to disable tests, force install on, pick install dirs.build(): standardcmake.configure() + cmake.build().package():cmake.install(), copy LICENSE tolicenses/,rmdir(self, "<package>/lib/cmake")etc. for cleanup. If upstream doesn't install a bundled static dep, copy it frombuild_folderby pattern.package_info(): declarecpp_info.libs,cmake_file_name,cmake_target_name. On Windows addsystem_libs(psapi, dbghelp, etc.) per upstream's link line. If consumed-as-static would leave unresolved symbols from a conan dep, setcpp_info.requires = ["<dep>::<dep>"].
If upstream's CMakeLists downloads a dep at configure time (e.g.
FetchContent, ExternalProject_Add), prefer patching it to call
find_package first and fall back to the bundled path. See
recipes/funchook/all/patches/1.1.3-external-capstone.patch for the
short-circuit pattern.
Step 4 - scaffold test_package
Three files:
test_package/conanfile.py— minimal, mirrors funchook's. Setstest_type = "explicit", requiresself.tested_reference_str, runs the built executable viaself.run(exe, env="conanrun")insidecan_run(self).test_package/CMakeLists.txt—find_package(<name> CONFIG REQUIRED), link against<name>::<name>.test_package/test_package.<c|cpp>— should exercise at least one symbol end-to-end so a successful exit means the package actually works, not just that linking succeeded. Watch for compiler inlining tripping up function hooking / pointer comparisons — mark relevant functionsNOINLINEand usevolatileif needed (see funchook's test_package).
STOP if you can't think of a meaningful end-to-end test. Ask the user for a snippet that exercises the library's main entrypoint.
Step 5 - local validation (Windows)
Run from project root with cmake on PATH:
$env:PATH = "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin;C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja;$env:PATH"
conan create recipes/<name>/all --version=<version> -pr default --build=missingIf the recipe has options, test the non-default value too:
conan create recipes/<name>/all --version=<version> -pr default --build=missing -o '<name>/*:<opt>=<value>'Iterate until Testing the package: Executing test prints the expected
output. Common failure modes:
Library '<name>-static' not found in package→ upstream'sOUTPUT_NAMEdiffers from the recipe'scpp_info.libs. Inspect the installed package folder (.conan2/p/b/<name>*/p/lib) and update.- Unresolved symbols → upstream installs the main lib but not a bundled
dep; either copy the bundled lib in
package()or patch upstream to usefind_package. - Test executable crashes with no useful output → ABI mismatch between
separate builds of the same lib (classic when patching a
find_packageshort-circuit but the conan dep isn't actually inrequires). Checkfind_package(<dep> CONFIG QUIET)actually succeeds —QUIEThides the miss.
Step 6 - Linux validation in a container
ubuntu:20.04 gives glibc 2.31, which is roughly the floor Endstone targets:
docker run --rm -v "<absolute project path>:/work" ubuntu:20.04 bash -c '
export DEBIAN_FRONTEND=noninteractive
apt-get update -qq >/dev/null
apt-get install -qq -y --no-install-recommends build-essential ninja-build python3 python3-pip ca-certificates >/dev/null
pip3 install --quiet --no-input "cmake>=3.29" "conan>=2.0"
export PATH=/usr/local/bin:$PATH HOME=/work/.linux-home
conan profile detect --force >/dev/null 2>&1 || true
conan create /work/recipes/<name>/all --version=<version> --build=missing 2>&1 | grep -E "<test-success-marker>|ERROR|Built target"
'After the run, delete the throwaway cache: rm -rf .linux-home.
Replace <test-success-marker> with a string the test_package prints on
success (e.g. hooked add for funchook).
Step 7 - upload to Cloudsmith
STOP before uploading. Confirm with the user the upload scope:
- Recipe only (default):
--only-recipe. Consumers build binaries locally on first install. Negligible Cloudsmith storage cost. - Recipe + binaries: drop
--only-recipe. Eachpackage_id× option combination uploaded contributes real storage. Only do this when CI is going to need the binaries.
The Cloudsmith remote is named endstone in .conan2/remotes.json. Auth
for upload requires HTTP Basic Auth with a personal Cloudsmith API key
(entitlement tokens are read-only). The user must run
conan remote login -p <api-key> endstone <cloudsmith-username> themselves
in their own shell — don't ask them to paste the key into chat.
Once authenticated:
conan upload "<name>/<version>" --only-recipe -r=endstone -cVerify:
conan list "<name>/*" -r=endstoneCloudsmith has a brief post-sync indexing step (~30s); if conan list
returns empty immediately after upload, wait and retry. The package
appearing on Cloudsmith's web UI doesn't always mean conan list sees it
yet.
For an end-to-end sanity check, blow away the local cache and re-pull:
conan remove "<name>/*" -c
conan install --requires=<name>/<version> -r=endstone --build=missingStep 8 - wire endstone to consume it (optional)
If the goal was to replace a FetchContent or to add a new dep, then:
- Add
self.requires("<name>/<version>")to the project rootconanfile.py. - Add
find_package(<name> CONFIG REQUIRED)in the consumingsrc/.../CMakeLists.txt(typicallysrc/endstone/runtime/CMakeLists.txtfor hook-related deps). - Update
target_link_libraries(...)to use<name>::<name>(most likely already named this way if you replaced a FetchContent alias). - Delete the old
third_party/<name>/folder and itsadd_subdirectory(<name>)line inthird_party/CMakeLists.txt. - Confirm
conan install . --build=missing -s compiler.cppstd=20 -c tools.cmake.cmaketoolchain:generator=Ninja ...succeeds.
The endstone Cloudsmith remote is already in tracked
.conan2/remotes.json; devs cloning the repo will resolve the dep without
any setup beyond pip install conan and conan profile detect.
Step 9 - commit
Stage only:
recipes/<name>/(the recipe folder).conan2/remotes.jsonif you added a new remoteconanfile.py, the CMakeLists changes, and any deletedthird_party/files if Step 8 was done- README badge / CONTRIBUTING edits if applicable
Do not stage test_package build artifacts (recipes/.gitignore already
excludes **/test_package/build/ and CMakeUserPresets.json). Leave the
project's pre-existing untracked files alone.
Commit style matches the repo's conventional-commit history:
build: add <name> conan recipeBody: one short paragraph explaining what the recipe wraps + which
platforms were validated, then a bullet list of notable recipe quirks
(bundled deps, patches, non-default cpp_info).
Never add a Co-Authored-By line for Claude.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

