1 files changed, 67 insertions, 0 deletions
diff --git a/tests/core/cgo/README.rst b/tests/core/cgo/README.rst
new file mode 100644
index 00000000..a385cab3
--- /dev/null
+++ b/tests/core/cgo/README.rst
@@ -0,0 +1,67 @@
+.. _#2067: https://github.com/bazelbuild/rules_go/issues/2067
+.. _#2622: https://github.com/bazelbuild/rules_go/issues/2622
+
+Basic cgo functionality
+=======================
+
+opts_test
+---------
+
+Checks that different sets of options are passed to C and C++ sources in a
+``go_library`` with ``cgo = True``.
+
+(generated_)?(versioned_)?dylib_test
+------------------------------------
+
+Checks that Go binaries can link against dynamic C libraries. Some libraries
+(especially those provided with ``cc_import``) may only have dynamic versions,
+and we should be able to link against them and find them at run-time.
+
+The non ``generated_`` tests are manual. The ``generate_imported_dylib.sh``
+script must be run before running the tests themselves.
+
+The ``generated_`` variants check that Go binaries can link against dynamic C
+libraries that are generated by another rule, rather than being included in the
+source tree.
+
+The ``versioned_`` variants check that Go binaries can link against dynamic C
+libraries that are only available as a versioned shared library, like
+``libfoo.so.1``, as used on Linux.
+
+cc_libs_test
+------------
+
+Checks that Go binaries that include cgo code may or may not link against
+libstdc++, depending on how they're linked. This tests several binaries:
+
+* ``pure_bin`` - built in ``"pure"`` mode, should not depend on libstdc++.
+* ``c_srcs`` - has no C++ code in sources, should not depend on libstdc++.
+* ``cc_srcs`` - has some C++ code in sources, should depend on libstdc++.
+* ``cc_deps`` - depends on a ``cc_library``, should depend on libstdc++
+  because we don't know what's in it.
+
+race_test
+---------
+
+Checks that cgo code in a binary with ``race = "on"`` is compiled in race mode.
+Verifies #1592.
+
+tag_test
+--------
+
+Checks that sources with ``// +build cgo`` are built when cgo is enabled
+(whether or not ``cgo = True`` is set), and sources with ``// +build !cgo``
+are only built in pure mode.
+
+cdeps_link_test
+---------------
+
+Checks that libraries in ``cdeps`` are linked into the generated ``_cgo_.o``
+executable used to produce ``_cgo_imports.go``. Verifies `#2067`_.
+
+split_import_test
+-----------------
+
+Checks that when a package with ``cdeps`` is recompiled due to a split test,
+the input files from ``cdeps`` are included in the recompilation and are passed
+to the linker. Verifies `#2622`_.