[docs] Update docs for OpenBSD.

When making debug builds, `Decl.cpp` compiles with a large number of ELF
section headers; including randomdata sections as normally included by
the platform for security purposes, this may in reality exceed the ELF
limit of `SHN_LORESERVE`.

In this case, the ELF header field containing the number of section
headers, `e_shnum`, is set to 0 and the real number of section headers
is stored elsewhere. However, when an object file has no section
headers, this field is also set to 0.

OpenBSD uses the GNU binutils by default. These binutils do not handle
the case when `e_shnum` is 0, and assume that the object file has no
section headers.  But the only tool that counts is the static archive
tool `ar`. When creating the archive index, `ar` encounters `Decl.cpp.o`
as part of `libswiftAST.a`, notes that `e_shnum` is 0, and skips the
object file entirely, presumably because it thinks the object file has
no section headers and therefore no symbols. This leads the linker to
assume that symbols in `Decl.cpp.o` are not part of `libswiftAST.a`,
when in fact they are.

The LLVM version of `ar` does not appear to have this bug.

Since this is only a problem that is more likely to occur on debug
builds and workarounds like enabling LTO can alleviate the problem, do
not recommend that the `llvm` package be added as part of the standard
package dependency set, but merely note that using `llvm-ar` can work
around the problem. Indeed, future OpenBSD versions may include updated
binutils which may have this bug fixed.

While we are here, the new concurrency features require libdispatch, and
since some of the necessary patches to libdispatch have not yet been
reviewed or accepted upstream yet to make it work on OpenBSD, recommend
that prospective builders for this platform still disable features that
depend on libdispatch for now.

Additionally, update the platform version number which has been tested.

Author: 3405691582

docs/OpenBSD.md

@@ -1,6 +1,6 @@
 # Getting started with Swift on OpenBSD
 
-Swift builds and runs on OpenBSD (tested on 6.8-beta), with some special considerations.
+Swift builds and runs on OpenBSD (tested on 6.8), with some special considerations.
 
 ## Preparing
 
@@ -66,7 +66,7 @@ These options are:
 * `--skip-build-clang-tools-extra` and `--skip-build-compiler-rt`: to ensure LLVM builds cleanly,
 * `--extra-cmake-options=`
   * `-DCMAKE_DISABLE_FIND_PACKAGE_Backtrace=TRUE,-DCMAKE_DISABLE_FIND_PACKAGE_LibXml2=TRUE,-DLLVM_VERSION_SUFFIX=''`: to ensure LLVM builds cleanly,
-  * `-DSWIFT_BUILD_SOURCEKIT=OFF,-DSWIFT_BUILD_SYNTAXPARSERLIB=OFF`: to ensure Swift does not attempt to build libdispatch, which is not yet supported on OpenBSD,
+  * `-DSWIFT_BUILD_SOURCEKIT=OFF,-DSWIFT_BUILD_SYNTAXPARSERLIB=OFF,-DSWIFT_ENABLE_EXPERIMENTAL_CONCURRENCY=OFF`: to ensure Swift does not attempt to build libdispatch, which is not yet supported on OpenBSD,
   * `-DSWIFT_USE_LINKER=lld`: to specify that `lld` should be used over `gold`,
   * `-DCMAKE_INSTALL_DIR=/usr/local"`: to set the correct platform install directory.
 
@@ -81,8 +81,11 @@ $ ./utils/build-script \
         -DLLVM_VERSION_SUFFIX='',\
         -DSWIFT_BUILD_SOURCEKIT=OFF,\
         -DSWIFT_BUILD_SYNTAXPARSERLIB=OFF,\
+        -DSWIFT_ENABLE_EXPERIMENTAL_CONCURRENCY=OFF,\
         -DSWIFT_USE_LINKER=lld,\
         -DCMAKE_INSTALL_DIR=/usr/local"
 ```
 
 You may wish to also supply the flag `--llvm-targets-to-build=host`, to speed up the LLVM build slightly.
+
+For debug builds especially, consider also installing the `llvm` package and setting `-DCMAKE_AR=/usr/local/bin/llvm-ar` with the `extra-cmake-options` flag, to work around problems creating indexes to archives containing object files with large numbers of section headers.