Skip to content

Commit 34a5402

Browse files
tomghuangtomghuang
authored
Merge pull request #135 from argtable/docs-add-conan-maintenance-guide
docs: add guide for updating conan center index recipe
2 parents f18b7b1 + 24830c4 commit 34a5402

File tree

4 files changed

+187
-0
lines changed

4 files changed

+187
-0
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ dist/
66
.archive/
77
.tags/
88
.misc/
9+
.venv/
910
.py*/
1011
docs/source/xml/
1112
docs/build/

‎docs/source/_static/conan-test.tar.gz

388 Bytes
Binary file not shown.

‎docs/source/_static/conan-test.zip

446 Bytes
Binary file not shown.

‎docs/source/arg_dev_conan.md

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Maintain Conan Center Index
2+
3+
**Conan** is an open-source, decentralized, and multi-platform C/C++ package
4+
manager that helps developers build applications and automate dependencies. It
5+
allows for the creation and sharing of binary packages, simplifying the process
6+
of integrating third-party libraries. The **Conan Center Index** is the official
7+
central repository for Conan recipes, hosting a vast collection of open-source
8+
C/C++ libraries. When a library like argtable3 is updated, its recipe in the
9+
Conan Center Index needs to be updated to make the new version available to the
10+
wider Conan community.
11+
12+
This document provides a step-by-step guide for updating the argtable3 recipe in
13+
the Conan Center Index. It outlines the necessary procedures to ensure that when
14+
a new version of the argtable3 library is released, Conan users can promptly
15+
access the latest updates through the central repository.
16+
17+
## Phase 1: Setting Up Your Environment
18+
19+
First, you need to prepare your local environment to work on the recipe.
20+
21+
1. **Prerequisites:**
22+
* **Git:** You must have Git installed.
23+
* **Python & Conan:** You need a working Python installation and the Conan
24+
package manager. If you don't have Conan, install it with pip:
25+
```bash
26+
python -m venv .venv
27+
.venv\Scripts\activate # On Windows
28+
# or
29+
source .venv/bin/activate # On Linux/macOS
30+
pip install conan
31+
```
32+
33+
2. **Fork and Clone Conan-Center-Index:**
34+
* Go to the `conan-io/conan-center-index` repository on GitHub and create a
35+
fork under your own account.
36+
* Clone your fork to your local machine:
37+
```bash
38+
git clone https://github.com/YOUR_USERNAME/conan-center-index.git
39+
cd conan-center-index
40+
```
41+
42+
3. **Create a New Branch:**
43+
It's crucial to make your changes on a new, descriptively named branch.
44+
```bash
45+
git checkout -b update-argtable3-to-3.3.0
46+
```
47+
48+
## Phase 2: Updating the `argtable3` Recipe
49+
50+
Now you will modify the files that define the `argtable3` package.
51+
52+
4. **Locate the Recipe:** The recipe for `argtable3` is located in
53+
`recipes/argtable3`. Navigate to the `recipes/argtable3/all` directory.
54+
55+
5. **Update `conandata.yml`:** This file stores data that is separate from the
56+
build logic, primarily the source code locations and checksums.
57+
* Open the `conandata.yml` file.
58+
* You will see entries for previous versions under the `sources` key. Add a
59+
new entry for your new release (e.g., `3.3.0`).
60+
* This entry needs the direct `url` to your new release's source archive
61+
(tar.gz or zip) and its `sha256` hash.
62+
```{note}
63+
**To get the SHA256 hash:**
64+
* Download the source archive for your new release.
65+
* Run one of the following commands:
66+
* **Linux:** `sha256sum argtable3-3.3.0.tar.gz`
67+
* **macOS:** `shasum -a 256 argtable3-3.3.0.tar.gz`
68+
* **PowerShell:** `Get-FileHash argtable3-3.3.0.tar.gz -Algorithm SHA256 | Select-Object -ExpandProperty Hash`
69+
```
70+
71+
72+
**Example `conandata.yml` addition:**
73+
```yaml
74+
sources:
75+
# ... existing versions ...
76+
"3.3.0":
77+
url: "https://github.com/argtable/argtable3/releases/download/v3.3.0.116da6c/argtable-v3.3.0.116da6c.tar.gz"
78+
sha256: "21d653eaab4b9dede76ceb0cb4e8878cf5cadb48ef9180c6a4d1a5cef1549e65"
79+
```
80+
81+
6. **Update `config.yml`:** This file maps package versions to the folder
82+
containing the recipe that builds them. For a simple version update where
83+
the build process hasn't changed, you just need to add the new version.
84+
* Open the `config.yml` file.
85+
* Add your new version (`3.3.0`) to the `versions` map, pointing it to the
86+
same recipe folder as the previous version.
87+
88+
**Example `config.yml` addition:**
89+
```yaml
90+
versions:
91+
# ... existing versions ...
92+
"3.3.0":
93+
folder: "all" # Or whatever folder the latest recipe is in
94+
```
95+
96+
7. **Review `conanfile.py`:** This is the main Python script that defines how
97+
to build the package. For a simple version bump where the build process,
98+
dependencies, and required patches have not changed, **you often do not need
99+
to modify this file at all.** The `conanfile.py` is usually written to be
100+
version-agnostic, pulling the version number and source URL from the
101+
metadata you just updated.
102+
103+
However, you should quickly review it to see if anything needs to change, such as:
104+
* Minimum required compiler versions.
105+
* Build options or CMake definitions that might have changed in `argtable3`.
106+
* Any patches that were applied to previous versions. Check if they are
107+
still needed for the new version or if they have been merged upstream.
108+
Patches are also listed in `conandata.yml`.
109+
110+
## Phase 3: Testing Your Changes Locally
111+
112+
**This is a critical, mandatory step.** Before submitting a pull request, you
113+
must verify that your updated recipe can build the package successfully on your
114+
local machine.
115+
116+
8. **Navigate to the Recipe Directory:** Make sure you are in the directory for
117+
the version you are updating (e.g., `recipes/argtable3/all`).
118+
119+
9. **Run `conan create`:**
120+
This command builds the package and runs a small test to ensure it's usable.
121+
```bash
122+
conan create . --version=3.3.0 --build=missing \
123+
-s build_type=Debug \
124+
-o shared=True \
125+
-s compiler.runtime=static
126+
```
127+
* `conan create .`: Tells Conan to build the recipe in the current directory.
128+
* `--version=3.3.0`: Explicitly tells Conan which version you are building (as defined in `config.yml` and `conandata.yml`).
129+
* `--build=missing`: Instructs Conan to build any missing dependencies from source if pre-built binaries aren't available.
130+
* `-s build_type=Debug`: Specifies the build type (you can also test with `Release`).
131+
* `-o shared=True`: Indicates that you want to build a shared library.
132+
* `-s compiler.runtime=static`: Specifies that you want to build with the MSVC static runtime (/MT or /MTd).
133+
```{note}
134+
You can test with `Makefile` in [conan-test.tar.gz](/_static/conan-test.tar.gz)
135+
on Linux or [conan-test.zip](_static/conan-test.zip) on Windows. This `Makefile`
136+
provides targets for building the `argtable3` package in various configurations,
137+
including debug and release builds, both shared and static libraries. It also
138+
includes a clean target to remove build artifacts. Extract `Makefile` to the
139+
`recipes/argtable3/all` directory and run:
140+
```bash
141+
make
142+
# Or for a specific build type:
143+
make debug
144+
# Or for a specific version:
145+
make ARGTABLE3_VERSION=3.3.0
146+
```
147+
148+
10. **Check the `test_package`:** The `conan create` command will automatically
149+
compile and run the code in the `test_package` subfolder. This test
150+
typically includes a small program that includes a header from your library
151+
and links against it. If this step passes, your local validation is likely
152+
successful.
153+
```{note}
154+
You can also run `conan test` to execute the tests defined in the `test_package` directory:
155+
```bash
156+
conan test /path/to/argtable3/test_package argtable3/3.3.0@
157+
```
158+
159+
## Phase 4: Submitting to Conan-Center-Index
160+
161+
Once your local tests pass, you are ready to create a pull request.
162+
163+
11. **Commit and Push:**
164+
Commit your changes to your branch and push them to your fork on GitHub.
165+
```bash
166+
git add .
167+
git commit -m "argtable3: Add version 3.3.0"
168+
git push -u origin update-argtable3-to-3.3.0
169+
```
170+
171+
12. **Create a Pull Request (PR):**
172+
* Go to your fork on GitHub. You should see a prompt to create a PR from your new branch.
173+
* The PR should be targeted at the `master` branch of the `conan-io/conan-center-index` repository.
174+
* **Title:** Use the standard format: `argtable3: Add version 3.3.0`.
175+
* **Description:** When you open the PR, a bot will post a comment with a
176+
checklist. **Read this checklist carefully** and check off the boxes that
177+
apply (e.g., "I've tested this locally," "I've updated conandata.yml,"
178+
etc.).
179+
180+
13. **Monitor the CI (Continuous Integration):** After you create the PR, a
181+
complex CI system will automatically start building your package on numerous
182+
platforms (Windows, Linux, macOS), compilers, and configurations.
183+
* Monitor the results of these builds. If any fail, you will need to
184+
investigate the logs and push fixes to your branch.
185+
* Once all checks pass, a maintainer will review and merge your PR, and your
186+
new `argtable3` version will become available on Conan-Center.

0 commit comments

Comments
 (0)