third_party/curl/README.fuchsia

Name: curl
URL: https://github.com/curl/curl
Version: 8.21.0
Revision: 68720b4837284335b2d63cb358f8f6ce65f5bc55
License: MIT/X derivate
License File: src/COPYING
CPEPrefix: cpe:/a:haxx:curl
Description: Curl is a command-line tool for transferring data specified with URL
syntax.
Revision is from `git merge-base JIRI_HEAD curl-8_21_0`.
Original URL: https://curl.haxx.se/
How to upgrade the version of curl:
  Note: All paths and terminal commands below assume execution from the
  `fuchsia.git` repository root unless noted.

  1. Identify current active version `<OLD_TAG>`:
     Read the `Version:` field at the top of `third_party/curl/README.fuchsia`
     (e.g., `8.18.0` maps to tag `curl-8_18_0`).
  2. Discover latest upstream stable release tag `<NEW_TAG>` and SHA-1:
     `git -C third_party/curl/src fetch origin`
     `git -C third_party/curl/src tag -l 'curl-*' --sort=-v:refname`
     (Select the highest non-beta stable release tag from the sorted output)
     `git -C third_party/curl/src show <NEW_TAG>`
  3. Update the curl pin in Jiri manifest `//manifests/third_party/all` to the
     new commit SHA-1.
  4. Sync the checkout to apply the manifest change:
     `jiri update -local-manifest-project=fuchsia`
  5. Identify added and deleted C/H source files between releases:
     `git -C third_party/curl/src diff --no-renames --diff-filter=AD \`
     `--name-status <OLD_TAG>..<NEW_TAG> -- lib src`
  6. Update source lists (`sources = [...]`) in `third_party/curl/BUILD.gn`:
     * Add newly introduced source files and remove deleted files for
       `libcurl` and `curl_bin`.
     * Ensure `curl_config` maintains `include_dirs` covering `src/lib` so
       internal headers relocated to subdirectories resolve parent includes.
  7. Evaluate configuration headers and generated sources:
     * Discover macro changes against dynamic autotools baseline:
       a. Run `autoreconf -fi` and `./configure --with-openssl`
          `--with-sysroot=$(realpath \`
          `../../prebuilt/third_party/sysroot/linux)` inside
          `third_party/curl/src/` to generate `lib/curl_config.h`.
       b. Diff generated baseline against active host config to discover new
          upstream feature macros and dead obsolete macros:
          `diff -u third_party/curl/curl_config.h.host`
          `third_party/curl/src/lib/curl_config.h`
       c. Delete `third_party/curl/src/lib/curl_config.h` immediately after
          diffing (`rm -f ...`). If left on disk, GN compilation prioritizes
          `src/lib/` over out directories, shadowing and ignoring your edits.
     * Synchronize `curl_config.h.host` and `curl_config.h.fuchsia`:
       a. Strip obsolete macros deleted from the autotools baseline.
       b. Adopt new upstream feature and resolver macros.
       c. Verify compiler feedback (`fx build`): if Zircon musl headers hide
          symbols (e.g., `memrchr`), set `/* #undef MACRO */` in `.fuchsia`
          to trigger curl internal fallback implementations (`Curl_memrchr`).
       Note: Mostly we want to only add or remove configs, not change any.
       Note that the same config file is used on both macOS and Linux.
     * Check CLI help text changes:
       `git -C third_party/curl/src diff --stat <OLD_TAG>..<NEW_TAG> --`
       `docs/cmdline-opts src/mkhelp.pl`
       If upstream added or modified CLI options, or if `fx build` fails with
       missing `hugehelp` symbols, regenerate `tool_hugehelp.c` per instructions
       at the bottom of this file.
  8. Run `fx gen` to stage platform-specific configuration headers into the out
     directory, and `fx build` to verify compilation.
  9. Make sure you delete or rename any intermediate generated
     `third_party/curl/src/lib/curl_config.h` when testing, or else your edits
     in `curl_config.h.host` and `curl_config.h.fuchsia` will not be picked up.
  10. Update `Version:` and `Revision:` metadata fields at the top of this file.

If you see missing symbols for `hugehelp`, you might need to regenerate `src/tool_hugehelp.c`:
  * Run the above configure steps..
  * `make -j10` will generate `src/tool_hugehelp.c`
  * Clean the intermediate curl object files from your out directory:
    `rm -rf $(fx get-build-dir)/{x64-shared,host_x64}/obj/third_party/curl/`
  * `fx gen` and `fx build` should resolve any missing symbols for `hugehelp`.
  * Commit the changes.
  * WARNING: `make clean` will delete `src/tool_hugehelp.c`.