README: document adding new dependencies

Signed-off-by: Benjamin Gilbert <bgilbert@cs.cmu.edu>

Author: bgilbert

README.md

@@ -27,7 +27,7 @@ The macOS SDK must be installed.
 
     ./bintool bdist
 
-## Substitute Sources
+## Substitute sources
 
 To override the source tree used to build a project, create a top-level
 directory named `override` and place the substitute source tree in a
@@ -70,3 +70,67 @@ Report the version number that will be used in archive file names.
 #### `projects`
 
 Report the IDs and display names of all component projects.
+
+## Adding a new dependency
+
+openslide-bin produces binaries which do not link with shared libraries from
+the build environment, except for specific platform libraries on each
+supported OS.  To add a library dependency to openslide-bin, you must
+configure openslide-bin to build that library itself.
+
+All dependencies must be built with [Meson][], even those that don't natively
+support Meson.  For many common libraries, a Meson port is available from
+Meson's [wrapdb][].  Otherwise, you'll need to port the library's build
+system to Meson and submit the port to wrapdb (or to the upstream project if
+its maintainers are interested).
+
+To add a dependency to openslide-bin:
+
+1. Use `meson wrap install` to add the dependency's wrap file from wrapdb
+   to the `subprojects` directory.
+2. Add the dependency to `_PROJECTS` in `common/software.py`.
+   - Test the `update_url` and `update_regex` by running `./bintool updates`.
+     A successful run will not produce an output line for the new dependency.
+3. Modify `deps/meson.build` to invoke the build, in the correct order
+   relative to the other dependencies.  Include any necessary build options,
+   e.g. disable building command-line tools to reduce build time.
+
+### Common problems
+
+New dependencies sometimes have build bugs that need to be fixed in wrapdb
+or upstream.  Common problems include:
+
+1. Libraries dllexporting their public symbols when built as a Windows static
+   library.  `dllexport` should only be used when building a dynamic library.
+2. Libraries taking an unintended dependency on pthreads.  Many libraries
+   use Windows threading primitives on Windows but unconditionally depend on
+   `dependency('threads')` in their `meson.build`, thus adding a dependency
+   on the pthreads library.  openslide-bin intentionally does not ship a
+   pthreads implementation.
+
+Either issue will cause the build or smoke test to fail.  The subproject can
+be patched by adding a patch file to the `subprojects/packagefiles`
+directory and adding a `diff_files` directive to the subproject's wrap file.
+
+### Submitting a PR
+
+When adding a new dependency to OpenSlide, the corresponding openslide-bin PR
+should be be submitted early in the development process, since OpenSlide's CI
+will not pass on Windows until the dependency is available in openslide-bin.
+The `subproject()` call in `deps/meson.build` should initially be gated
+behind `if dev_deps`, causing the new subproject to be omitted from
+openslide-bin releases until the feature lands in an OpenSlide release.
+
+All openslide-bin subprojects must use wraps from wrapdb, so new Meson ports
+should be submitted there first.  (wrapdb does not expect ports to include
+all functionality from the upstream build system.  For example, obscure
+options and CPU architectures can be omitted.)  As an exception, wraps for
+newly-developed libraries can point directly to an upstream Git commit while
+the library is being integrated into OpenSlide.  However, the wrap must be
+added to wrapdb before the first OpenSlide release that uses the library.
+
+Similarly, all `diff_files` directives in wrap files must have a comment
+linking to a wrapdb PR or upstream PR for the patch.
+
+[Meson]: https://mesonbuild.com/
+[wrapdb]: https://github.com/mesonbuild/wrapdb