third-party/README.md

   1 hhvm-third-party
   2 ================
   3
   4 All of the dependencies that [hhvm](https://github.com/facebook/hhvm) needs which don't have distribution/homebrew
   5 packages.
   6
   7 Updating Facebook dependencies
   8 ------------------------------
   9
  10 Facebook dependencies (e.g. folly, thrift, proxygen) should all be updated simultaneously, to identical versions.
  11
  12 Some tips:
  13
  14 - work in the oldest supported Linux distribution; this gets you the oldest C++ compiler and the oldest CMake, so you'll hopefully get most of the possible errors in your interactive environment, rather than hours later on CI
  15 - it's also worth setting up an interactive build environment on your mac; if CI fails, try uninstalling the package from homebrew then figure out how to make the build pass without it
  16 - it's easiest to do this with a separate build directory (e.g. `build/` or `obj-x86_64-linux-gnu`), as this lets you easily delete all the relevant build state/artifacts without deleting your changes to the source and cmake.
  17 - several of these projects need patching; these can have several patch files in `patches/`, and they are applied in the order listed in `series`. [quilt](https://wiki.debian.org/UsingQuilt) can be used to manage these as a form of source control, and is usually worth configuring.
  18   - The build will use quilt to apply patches if you `export HHVM_TP_QUILT=$(which quilt)`; you may need to delete `$BUILD_DIR/third-party/` after setting that to get a clean build.
  19   - If patches fail to apply or more are needed:
  20     1. `cd` to the extracted source directory, e.g. `$BUILD_DIR/third-party/folly/bundled_folly-prefix/src/bundled_folly`
  21     2. `export QUILT_PATCHES=$SOURCE_DIR/third-party/$PROJECT/patches`
  22     3. `quilt push -a`
  23     4. If it fails because the patch has already been applied, use `quilt delete PATCH_NAME_HERE.patch`; if it is still needed but needs updates, use `quilt push -f` to produce a `.rej` (rejected changes) file, manually apply the changes, then run `quilt refresh` when you are done
  24     5. if you need to add additional files to the patch, use `quilt add FILE` **before** editing the file, then `quilt refresh` when you are done
  25     6. if you need to add an additional patch, use `quilt new MY_PATCH.patch`, `quilt add FILE`, `quilt refresh`
  26     7. if you want to update all the patches with current line numbers etc, run `quilt pop -a --refresh`
  27
  28 Some Facebook-employee-specific tips:
  29
  30 - you can allocate a VM with a recent prebuilt environment via `i opensource/ondemand/facebook/hhvm`; when prompted, slect the most recent successfull built for the oldest Ubuntu listed.
  31 - if the Mac CI is unable to find a dependency but it's found locally, uninstall it with `brew uninstall --force --ignore-dependencies FOO`; you can then install the same package used in the CI with `yum install`; find the package with `yum search foo` - you probably want the most recent `nix2rpm` package, though you can check exactly which is used in `hphp/facebook/autobuild/cmake/mac/cmake.sh`
  32
  33 Overall process:
  34
  35 1. Get a working build environment (ideally one on old Ubuntu, one on MacOS)
  36 2. Most FB projects should be fetching release tarballs with tags like `vYYYY.MM.DD.00`; full download URLs are listed in third-party/foo/CMakeLists.txt. Update these tags to the version you're targetting.
  37 3. Download all of the URLs you just modified. For some projects, this will give you `vYYYY.MM.DD.00.tar.gz`, rename to `PROJECT-vYYYY.MM.DD.00.tar.gz`
  38 4. Update the hashes in `third-party/foo/CMakeLists.txt` to match `openssl dgst -sha256 *.tar.gz`
  39 5. **Requires FB employee**: update our CI caches - this can be done on your laptop, it does not need a devserver.
  40    `for file in *; do manifold put $file hhvm_opensource_dependency_cache/flat/$file; done`
  41 6. Update any submodules to a compatible commit from the same day. As of 2021-10-14, this is only needed for mcrouter.
  42 7. Try to build; fix any patches/build issues
  43 8. Create pull request and (requires FB employee) diff
  44 9. If you were working in Ubuntu, pull onto MacOS and do a local test build. If you were working in MacOS, pull into Ubuntu and do a test build
  45 10. Land once everything's good :) Don't do this on a Friday.
  46 11. Check nightly build results the next day. Fix any portability issues that weren't caught by CI.
  47
  48
  49 LICENSING
  50 ---------
  51
  52 Various licenses are used in this project; see the notices in relevant files and subdirectories for details.