diff --git a/cmake/ExperimentalFeatures.cmake b/cmake/ExperimentalFeatures.cmake
index f23bfe3762c..57a66e68daa 100644
--- a/cmake/ExperimentalFeatures.cmake
+++ b/cmake/ExperimentalFeatures.cmake
@@ -1,8 +1,19 @@
+# Experimental feature support for libgit2 - developers can opt in to
+# experimental functionality, like sha256 support. When experimental
+# functionality is enabled, we set both a cmake flag *and* a compile
+# definition. The cmake flag is used to generate `experimental.h`,
+# which will be installed by a `make install`. But the compile definition
+# is used by the libgit2 sources to detect the functionality at library
+# build time. This allows us to have an in-tree `experimental.h` with
+# *no* experiments enabled. This lets us support users who build without
+# cmake and cannot generate the `experimental.h` file.
+
 if(EXPERIMENTAL_SHA256)
 	add_feature_info("SHA256 API" ON "experimental SHA256 APIs")
 
 	set(EXPERIMENTAL 1)
 	set(GIT_EXPERIMENTAL_SHA256 1)
+	add_compile_definitions(GIT_EXPERIMENTAL_SHA256)
 else()
 	add_feature_info("SHA256 API" OFF "experimental SHA256 APIs")
 endif()
diff --git a/include/git2/experimental.h b/include/git2/experimental.h
new file mode 100644
index 00000000000..06435f9a76a
--- /dev/null
+++ b/include/git2/experimental.h
@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) the libgit2 contributors. All rights reserved.
+ *
+ * This file is part of libgit2, distributed under the GNU GPL v2 with
+ * a Linking Exception. For full terms see the included COPYING file.
+ */
+
+#ifndef INCLUDE_experimental_h__
+#define INCLUDE_experimental_h__
+
+/*
+ * This file exists to support users who build libgit2 with a bespoke
+ * build system and do not use our cmake configuration. Normally, cmake
+ * will create `experimental.h` from the `experimental.h.in` file and
+ * will include the generated file instead of this one. For non-cmake
+ * users, we bundle this `experimental.h` file which will be used
+ * instead.
+ */
+
+#endif
diff --git a/src/libgit2/experimental.h.in b/src/libgit2/experimental.h.in
index 3d6e931e23b..25fb14b9d17 100644
--- a/src/libgit2/experimental.h.in
+++ b/src/libgit2/experimental.h.in
@@ -1,3 +1,10 @@
+/*
+ * Copyright (C) the libgit2 contributors. All rights reserved.
+ *
+ * This file is part of libgit2, distributed under the GNU GPL v2 with
+ * a Linking Exception. For full terms see the included COPYING file.
+ */
+
 #ifndef INCLUDE_experimental_h__
 #define INCLUDE_experimental_h__
 
diff --git a/tests/libgit2/core/oid.c b/tests/libgit2/core/oid.c
index 9fe4413b7a0..90fb37514ba 100644
--- a/tests/libgit2/core/oid.c
+++ b/tests/libgit2/core/oid.c
@@ -52,7 +52,9 @@ void test_core_oid__streq_sha1(void)
 
 void test_core_oid__streq_sha256(void)
 {
-#ifdef GIT_EXPERIMENTAL_SHA256
+#ifndef GIT_EXPERIMENTAL_SHA256
+	cl_skip();
+#else
 	cl_assert_equal_i(0, git_oid_streq(&id_sha256, str_oid_sha256));
 	cl_assert_equal_i(-1, git_oid_streq(&id_sha256, "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"));
 
@@ -90,7 +92,9 @@ void test_core_oid__strcmp_sha1(void)
 
 void test_core_oid__strcmp_sha256(void)
 {
-#ifdef GIT_EXPERIMENTAL_SHA256
+#ifndef GIT_EXPERIMENTAL_SHA256
+	cl_skip();
+#else
 	cl_assert_equal_i(0, git_oid_strcmp(&id_sha256, str_oid_sha256));
 	cl_assert(git_oid_strcmp(&id_sha256, "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef") < 0);
 
@@ -129,7 +133,9 @@ void test_core_oid__ncmp_sha1(void)
 
 void test_core_oid__ncmp_sha256(void)
 {
-#ifdef GIT_EXPERIMENTAL_SHA256
+#ifndef GIT_EXPERIMENTAL_SHA256
+	cl_skip();
+#else
 	cl_assert(!git_oid_ncmp(&id_sha256, &idp_sha256, 0));
 	cl_assert(!git_oid_ncmp(&id_sha256, &idp_sha256, 1));
 	cl_assert(!git_oid_ncmp(&id_sha256, &idp_sha256, 2));
diff --git a/tests/libgit2/odb/loose.c b/tests/libgit2/odb/loose.c
index e7952547884..0409dfb2812 100644
--- a/tests/libgit2/odb/loose.c
+++ b/tests/libgit2/odb/loose.c
@@ -160,7 +160,9 @@ void test_odb_loose__exists_sha1(void)
 
 void test_odb_loose__exists_sha256(void)
 {
-#ifdef GIT_EXPERIMENTAL_SHA256
+#ifndef GIT_EXPERIMENTAL_SHA256
+	cl_skip();
+#else
 	git_oid id, id2;
 	git_odb *odb;
 	git_odb_options odb_opts = GIT_ODB_OPTIONS_INIT;
@@ -201,7 +203,9 @@ void test_odb_loose__simple_reads_sha1(void)
 
 void test_odb_loose__simple_reads_sha256(void)
 {
-#ifdef GIT_EXPERIMENTAL_SHA256
+#ifndef GIT_EXPERIMENTAL_SHA256
+	cl_skip();
+#else
 	test_read_object(&commit_sha256);
 	test_read_object(&tree_sha256);
 	test_read_object(&tag_sha256);
@@ -230,7 +234,9 @@ void test_odb_loose__streaming_reads_sha1(void)
 
 void test_odb_loose__streaming_reads_sha256(void)
 {
-#ifdef GIT_EXPERIMENTAL_SHA256
+#ifndef GIT_EXPERIMENTAL_SHA256
+	cl_skip();
+#else
 	size_t blocksizes[] = { 1, 2, 4, 16, 99, 1024, 123456789 };
 	size_t i;
 
@@ -259,7 +265,9 @@ void test_odb_loose__read_header_sha1(void)
 
 void test_odb_loose__read_header_sha256(void)
 {
-#ifdef GIT_EXPERIMENTAL_SHA256
+#ifndef GIT_EXPERIMENTAL_SHA256
+	cl_skip();
+#else
 	test_read_header(&commit_sha256);
 	test_read_header(&tree_sha256);
 	test_read_header(&tag_sha256);