* [Cluster-devel] [PATCH 0/3] gfs2-utils: Unit test framework improvements
@ 2020-09-11 14:42 Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 1/3] Reorganise unit tests Andrew Price
` (2 more replies)
0 siblings, 3 replies; 4+ messages in thread
From: Andrew Price @ 2020-09-11 14:42 UTC (permalink / raw)
To: cluster-devel.redhat.com
To date we haven't accumulated many unit tests. That's partly because the older code was never written with testability in mind and partly because the unit test infrastructure is poorly organised in the project.
This patch set aims to lower the effort needed to write new unit tests by stubbing out all of the infrastructure required and by moving the unit tests into the directories of the code they're testing. Doing that also means that the main testsuite script is no longer dependent on the unit tests and can more easily be used outside of the source directory, e.g. for CI.
Andrew Price (3):
Reorganise unit tests
Stub out unit tests for the main gfs2-utils
Describe the unit tests in README.tests
.gitignore | 14 ++++--
doc/README.tests | 31 ++++++++++++-
gfs2/convert/Makefile.am | 4 ++
gfs2/convert/check_convert.c | 27 +++++++++++
gfs2/convert/checks.am | 7 +++
gfs2/convert/gfs2_convert.c | 2 +
gfs2/edit/Makefile.am | 3 ++
gfs2/edit/check_edit.c | 27 +++++++++++
gfs2/edit/checks.am | 7 +++
gfs2/edit/hexedit.c | 2 +
gfs2/fsck/Makefile.am | 4 ++
gfs2/fsck/check_fsck.c | 27 +++++++++++
gfs2/fsck/checks.am | 7 +++
gfs2/fsck/main.c | 2 +
gfs2/libgfs2/Makefile.am | 21 +++++----
gfs2/libgfs2/check_libgfs2.c | 21 +++++++++
gfs2/libgfs2/check_meta.c | 21 +++++++++
{tests => gfs2/libgfs2}/check_rgrp.c | 67 ++++++++++++----------------
gfs2/libgfs2/checks.am | 32 +++++++++++++
gfs2/mkfs/Makefile.am | 3 ++
gfs2/mkfs/check_grow.c | 27 +++++++++++
gfs2/mkfs/check_jadd.c | 27 +++++++++++
gfs2/mkfs/check_mkfs.c | 27 +++++++++++
gfs2/mkfs/checks.am | 17 +++++++
gfs2/mkfs/main_grow.c | 2 +
gfs2/mkfs/main_jadd.c | 2 +
gfs2/mkfs/main_mkfs.c | 2 +
gfs2/tune/Makefile.am | 4 ++
gfs2/tune/check_tune.c | 27 +++++++++++
gfs2/tune/checks.am | 7 +++
gfs2/tune/main.c | 2 +
tests/Makefile.am | 53 ++--------------------
tests/check_meta.c | 33 --------------
tests/libgfs2.at | 9 ----
tests/testsuite.at | 1 -
35 files changed, 421 insertions(+), 148 deletions(-)
create mode 100644 gfs2/convert/check_convert.c
create mode 100644 gfs2/convert/checks.am
create mode 100644 gfs2/edit/check_edit.c
create mode 100644 gfs2/edit/checks.am
create mode 100644 gfs2/fsck/check_fsck.c
create mode 100644 gfs2/fsck/checks.am
create mode 100644 gfs2/libgfs2/check_libgfs2.c
create mode 100644 gfs2/libgfs2/check_meta.c
rename {tests => gfs2/libgfs2}/check_rgrp.c (62%)
create mode 100644 gfs2/libgfs2/checks.am
create mode 100644 gfs2/mkfs/check_grow.c
create mode 100644 gfs2/mkfs/check_jadd.c
create mode 100644 gfs2/mkfs/check_mkfs.c
create mode 100644 gfs2/mkfs/checks.am
create mode 100644 gfs2/tune/check_tune.c
create mode 100644 gfs2/tune/checks.am
delete mode 100644 tests/check_meta.c
delete mode 100644 tests/libgfs2.at
--
2.26.2
^ permalink raw reply [flat|nested] 4+ messages in thread
* [Cluster-devel] [PATCH 1/3] Reorganise unit tests
2020-09-11 14:42 [Cluster-devel] [PATCH 0/3] gfs2-utils: Unit test framework improvements Andrew Price
@ 2020-09-11 14:42 ` Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 2/3] Stub out unit tests for the main gfs2-utils Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 3/3] Describe the unit tests in README.tests Andrew Price
2 siblings, 0 replies; 4+ messages in thread
From: Andrew Price @ 2020-09-11 14:42 UTC (permalink / raw)
To: cluster-devel.redhat.com
Move the libgfs2 unit tests out of the main testsuite and into the
libgfs2 directory. They are still run in 'make check' but the new
organisation means we have the tests closer to the code that they're
testing and the main testsuite script no longer needs exceptions for
running outside of the source tree (e.g. for CI).
Also rework the libgfs2 unit tests so that they're built as several
suites in one executable. This simplifies the build rules.
The setup and teardown code for the mocked structures in the rgrp.c unit
tests is now implemented as libcheck 'fixtures' that are run for each
test case.
The automake rules for building unit tests are now separated into a
checks.am file that is included depending on whether libcheck is
available.
Signed-off-by: Andrew Price <anprice@redhat.com>
---
.gitignore | 7 ++-
gfs2/libgfs2/Makefile.am | 21 +++++----
gfs2/libgfs2/check_libgfs2.c | 21 +++++++++
gfs2/libgfs2/check_meta.c | 21 +++++++++
{tests => gfs2/libgfs2}/check_rgrp.c | 67 ++++++++++++----------------
gfs2/libgfs2/checks.am | 32 +++++++++++++
tests/Makefile.am | 53 ++--------------------
tests/check_meta.c | 33 --------------
tests/libgfs2.at | 9 ----
tests/testsuite.at | 1 -
10 files changed, 119 insertions(+), 146 deletions(-)
create mode 100644 gfs2/libgfs2/check_libgfs2.c
create mode 100644 gfs2/libgfs2/check_meta.c
rename {tests => gfs2/libgfs2}/check_rgrp.c (62%)
create mode 100644 gfs2/libgfs2/checks.am
delete mode 100644 tests/check_meta.c
delete mode 100644 tests/libgfs2.at
diff --git a/.gitignore b/.gitignore
index eee6a6bc..133e8071 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,6 +31,8 @@ cscope.out
*.o
*.la
*.lo
+*.trs
+*.log
gfs2/convert/gfs2_convert
gfs2/edit/gfs2_edit
gfs2/libgfs2/gfs2l
@@ -38,6 +40,7 @@ gfs2/libgfs2/parser.c
gfs2/libgfs2/parser.h
gfs2/libgfs2/lexer.c
gfs2/libgfs2/lexer.h
+gfs2/libgfs2/check_libgfs2
gfs2/fsck/fsck.gfs2
gfs2/glocktop/glocktop
gfs2/mkfs/mkfs.gfs2
@@ -46,13 +49,9 @@ gfs2/mkfs/gfs2_jadd
gfs2/scripts/82-gfs2-withdraw.rules
gfs2/tune/tunegfs2
test-driver
-tests/check_meta
-tests/check_rgrp
tests/nukerg
tests/testvol
-tests/testsuite.log
tests/testsuite.dir
-tests/testsuite.trs
tests/atconfig
tests/atlocal
tests/package.m4
diff --git a/gfs2/libgfs2/Makefile.am b/gfs2/libgfs2/Makefile.am
index 03a955f2..e614415e 100644
--- a/gfs2/libgfs2/Makefile.am
+++ b/gfs2/libgfs2/Makefile.am
@@ -12,6 +12,12 @@ BUILT_SOURCES = \
AM_LFLAGS = --header-file=lexer.h
AM_YFLAGS = -d
+AM_CPPFLAGS = \
+ -D_FILE_OFFSET_BITS=64 \
+ -D_LARGEFILE64_SOURCE \
+ -D_GNU_SOURCE \
+ -I$(top_srcdir)/gfs2/include \
+ $(uuid_CFLAGS)
noinst_HEADERS = \
libgfs2.h \
@@ -43,13 +49,6 @@ libgfs2_la_SOURCES = \
structures.c \
meta.c
-libgfs2_la_CPPFLAGS = \
- -D_FILE_OFFSET_BITS=64 \
- -D_LARGEFILE64_SOURCE \
- -D_GNU_SOURCE \
- -I$(top_srcdir)/gfs2/include \
- $(uuid_CFLAGS)
-
gfs2l_SOURCES = \
gfs2l.c \
lang.c \
@@ -58,11 +57,11 @@ gfs2l_SOURCES = \
gfs2l_LDADD = \
libgfs2.la \
$(uuid_LIBS)
-gfs2l_CPPFLAGS = \
- -I$(top_srcdir)/gfs2/include \
- -D_FILE_OFFSET_BITS=64 \
- $(uuid_CFLAGS)
# Autotools can't handle header files output by flex so we have to generate it manually
lexer.h: lexer.l
$(LEX) -o lexer.c $(AM_LFLAGS) $^
+
+if HAVE_CHECK
+include checks.am
+endif
diff --git a/gfs2/libgfs2/check_libgfs2.c b/gfs2/libgfs2/check_libgfs2.c
new file mode 100644
index 00000000..0cfe08f2
--- /dev/null
+++ b/gfs2/libgfs2/check_libgfs2.c
@@ -0,0 +1,21 @@
+#include <check.h>
+#include "libgfs2.h"
+
+// TODO: Remove this when the extern is removed from libgfs2
+void print_it(const char *label, const char *fmt, const char *fmt2, ...) {}
+
+extern Suite *suite_meta(void);
+extern Suite *suite_rgrp(void);
+
+int main(void)
+{
+ int failures;
+
+ SRunner *runner = srunner_create(suite_meta());
+ srunner_add_suite(runner, suite_rgrp());
+
+ srunner_run_all(runner, CK_ENV);
+ failures = srunner_ntests_failed(runner);
+ srunner_free(runner);
+ return failures ? 1 : 0;
+}
diff --git a/gfs2/libgfs2/check_meta.c b/gfs2/libgfs2/check_meta.c
new file mode 100644
index 00000000..4f4546f2
--- /dev/null
+++ b/gfs2/libgfs2/check_meta.c
@@ -0,0 +1,21 @@
+#include <check.h>
+#include "libgfs2.h"
+
+Suite *suite_meta(void);
+
+START_TEST(test_lgfs2_meta)
+{
+ ck_assert(lgfs2_selfcheck() == 0);
+}
+END_TEST
+
+Suite *suite_meta(void)
+{
+ Suite *s = suite_create("meta.c");
+
+ TCase *tc_meta = tcase_create("Metadata description self-check");
+ tcase_add_test(tc_meta, test_lgfs2_meta);
+ suite_add_tcase(s, tc_meta);
+
+ return s;
+}
diff --git a/tests/check_rgrp.c b/gfs2/libgfs2/check_rgrp.c
similarity index 62%
rename from tests/check_rgrp.c
rename to gfs2/libgfs2/check_rgrp.c
index 3d8a5ed0..4cf01754 100644
--- a/tests/check_rgrp.c
+++ b/gfs2/libgfs2/check_rgrp.c
@@ -1,19 +1,20 @@
#include <check.h>
-#include <libgfs2.h>
-#include <rgrp.h> /* Private header libgfs2/rgrp.h for convenience */
+#include "libgfs2.h"
+#include "rgrp.h" /* Private header libgfs2/rgrp.h for convenience */
-// TODO: Remove this when the extern is removed from libgfs2
-void print_it(const char *label, const char *fmt, const char *fmt2, ...) {}
+Suite *suite_rgrp(void);
-static lgfs2_rgrps_t mockup_rgrp(void)
+lgfs2_rgrps_t tc_rgrps;
+
+static void mockup_rgrps(void)
{
struct gfs2_sbd *sdp;
lgfs2_rgrps_t rgs;
- unsigned i;
uint64_t addr;
struct gfs2_rindex ri = {0};
lgfs2_rgrp_t rg;
uint32_t rgsize = (1024 << 20) / 4096;
+ int ret;
sdp = calloc(1, sizeof(*sdp));
ck_assert(sdp != NULL);
@@ -34,25 +35,25 @@ static lgfs2_rgrps_t mockup_rgrp(void)
rg = lgfs2_rgrps_append(rgs, &ri, 0);
ck_assert(rg != NULL);
- for (i = 0; i < rg->ri.ri_length; i++) {
- rg->bits[i].bi_data = calloc(1, sdp->bsize);
- ck_assert(rg->bits[i].bi_data != NULL);
- }
- return rgs;
+ ret = lgfs2_rgrp_bitbuf_alloc(rg);
+ ck_assert(ret == 0);
+ ck_assert(rg->bits[0].bi_data != NULL);
+
+ tc_rgrps = rgs;
}
-START_TEST(test_mockup_rgrp)
+static void teardown_rgrps(void)
{
- lgfs2_rgrps_t rgs = mockup_rgrp();
- ck_assert(rgs != NULL);
+ free(tc_rgrps->sdp);
+ lgfs2_rgrp_bitbuf_free(lgfs2_rgrp_first(tc_rgrps));
+ lgfs2_rgrps_free(&tc_rgrps);
}
-END_TEST
START_TEST(test_rbm_find_good)
{
uint32_t minext;
struct lgfs2_rbm rbm = {0};
- lgfs2_rgrps_t rgs = mockup_rgrp();
+ lgfs2_rgrps_t rgs = tc_rgrps;
rbm.rgd = lgfs2_rgrp_first(rgs);
/* Check that extent sizes up to the whole rg can be found */
@@ -76,7 +77,7 @@ START_TEST(test_rbm_find_bad)
int err;
uint32_t minext;
struct lgfs2_rbm rbm = {0};
- lgfs2_rgrps_t rgs = mockup_rgrp();
+ lgfs2_rgrps_t rgs = tc_rgrps;
rbm.rgd = lgfs2_rgrp_first(rgs);
minext = rbm.rgd->ri.ri_data + 1;
@@ -94,7 +95,7 @@ START_TEST(test_rbm_find_lastblock)
uint32_t minext = 1; /* Only looking for one block */
struct lgfs2_rbm rbm = {0};
lgfs2_rgrp_t rg;
- lgfs2_rgrps_t rgs = mockup_rgrp();
+ lgfs2_rgrps_t rgs = tc_rgrps;
rbm.rgd = rg = lgfs2_rgrp_first(rgs);
@@ -114,30 +115,18 @@ START_TEST(test_rbm_find_lastblock)
}
END_TEST
-static Suite * libgfs2_suite(void)
+Suite *suite_rgrp(void)
{
- Suite *s = suite_create("libgfs2");
-
- TCase *tc_rgrp = tcase_create("rgrp");
+ Suite *s = suite_create("rgrp.c");
- tcase_add_test(tc_rgrp, test_mockup_rgrp);
- tcase_add_test(tc_rgrp, test_rbm_find_good);
- tcase_add_test(tc_rgrp, test_rbm_find_bad);
- tcase_add_test(tc_rgrp, test_rbm_find_lastblock);
- tcase_set_timeout(tc_rgrp, 0);
- suite_add_tcase(s, tc_rgrp);
+ TCase *tc_rbm_find = tcase_create("rbm_find");
+ tcase_add_checked_fixture(tc_rbm_find, mockup_rgrps, teardown_rgrps);
+ tcase_add_test(tc_rbm_find, test_rbm_find_good);
+ tcase_add_test(tc_rbm_find, test_rbm_find_bad);
+ tcase_add_test(tc_rbm_find, test_rbm_find_lastblock);
+ tcase_set_timeout(tc_rbm_find, 0);
+ suite_add_tcase(s, tc_rbm_find);
return s;
}
-
-int main(void)
-{
- int failures;
- Suite *s = libgfs2_suite();
- SRunner *sr = srunner_create(s);
- srunner_run_all(sr, CK_NORMAL);
- failures = srunner_ntests_failed(sr);
- srunner_free(sr);
- return failures ? EXIT_FAILURE : EXIT_SUCCESS;
-}
diff --git a/gfs2/libgfs2/checks.am b/gfs2/libgfs2/checks.am
new file mode 100644
index 00000000..ff4b7583
--- /dev/null
+++ b/gfs2/libgfs2/checks.am
@@ -0,0 +1,32 @@
+TESTS = check_libgfs2
+check_PROGRAMS = $(TESTS)
+
+check_libgfs2_SOURCES = \
+ check_libgfs2.c \
+ meta.c check_meta.c \
+ rgrp.c check_rgrp.c \
+ block_list.c \
+ crc32c.c \
+ fs_geometry.c \
+ gfs2_disk_hash.c \
+ ondisk.c \
+ buf.c \
+ device_geometry.c \
+ fs_ops.c \
+ structures.c \
+ config.c \
+ fs_bits.c \
+ gfs1.c \
+ misc.c \
+ recovery.c \
+ super.c
+
+check_libgfs2_CFLAGS = \
+ -I$(top_srcdir)/gfs2/libgfs2 \
+ -I$(top_srcdir)/gfs2/include \
+ $(check_CFLAGS) \
+ $(uuid_CFLAGS)
+
+check_libgfs2_LDADD = \
+ $(check_LIBS) \
+ $(uuid_LIBS)
diff --git a/tests/Makefile.am b/tests/Makefile.am
index f8ce3740..11d848cd 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -30,45 +30,6 @@ nukerg_LDADD = \
$(top_builddir)/gfs2/libgfs2/libgfs2.la \
$(uuid_LIBS)
-if HAVE_CHECK
-UNIT_TESTS = \
- check_meta \
- check_rgrp
-UNIT_SOURCES = \
- $(top_srcdir)/gfs2/libgfs2/libgfs2.h
-UNIT_CFLAGS = \
- -I$(top_srcdir)/gfs2/libgfs2 \
- -I$(top_srcdir)/gfs2/include \
- @check_CFLAGS@
-UNIT_LDADD = \
- $(top_builddir)/gfs2/libgfs2/libgfs2.la \
- @check_LIBS@
-UNIT_CPPFLAGS = \
- -D_FILE_OFFSET_BITS=64 \
- -D_LARGEFILE64_SOURCE \
- -D_GNU_SOURCE
-
-check_PROGRAMS = $(UNIT_TESTS)
-
-check_meta_SOURCES = \
- $(UNIT_SOURCES) \
- check_meta.c
-check_meta_CFLAGS = $(UNIT_CFLAGS)
-check_meta_LDADD = \
- $(UNIT_LDADD) \
- $(uuid_LIBS)
-check_meta_CPPFLAGS = $(UNIT_CPPFLAGS)
-
-check_rgrp_SOURCES = \
- $(UNIT_SOURCES) \
- check_rgrp.c
-check_rgrp_CFLAGS = $(UNIT_CFLAGS)
-check_rgrp_LDADD = \
- $(UNIT_LDADD) \
- $(uuid_LIBS)
-check_rgrp_CPPFLAGS = $(UNIT_CPPFLAGS)
-endif
-
# The `:;' works around a Bash 3.2 bug when the output is not writable.
package.m4: $(top_srcdir)/configure.ac
:;{ \
@@ -91,21 +52,15 @@ TESTSUITE_AT = \
testsuite.at \
mkfs.at \
fsck.at \
- edit.at \
- libgfs2.at
-
-if HAVE_CHECK
-ENABLE_UNIT=yes
-endif
+ edit.at
TESTSUITE = testsuite
check-local: atconfig atlocal $(TESTSUITE)
- $(SHELL) '$(TESTSUITE)' ENABLE_UNIT_TESTS=$(ENABLE_UNIT) $(TOPTS)
+ $(SHELL) '$(TESTSUITE)' $(TOPTS)
installcheck-local: atconfig atlocal $(TESTSUITE)
- $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(sbindir):gfs2/libgfs2:tests' \
- ENABLE_UNIT_TESTS=$(ENABLE_UNIT) $(TOPTS)
+ $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(sbindir):gfs2/libgfs2:tests' $(TOPTS)
clean-local:
test ! -f '$(TESTSUITE)' || $(SHELL) '$(TESTSUITE)' --clean
@@ -117,6 +72,6 @@ atconfig: $(top_builddir)/config.status
AUTOM4TE = $(SHELL) $(top_srcdir)/missing --run autom4te
AUTOTEST = $(AUTOM4TE) --language=autotest
-$(TESTSUITE): $(TESTSUITE_AT) package.m4 $(UNIT_TESTS)
+$(TESTSUITE): $(TESTSUITE_AT) package.m4
$(AUTOTEST) -I '$(srcdir)' -o $@.tmp $@.at
mv $@.tmp $@
diff --git a/tests/check_meta.c b/tests/check_meta.c
deleted file mode 100644
index 8c7fab1f..00000000
--- a/tests/check_meta.c
+++ /dev/null
@@ -1,33 +0,0 @@
-#include <check.h>
-#include "libgfs2.h"
-
-// TODO: Remove this when the extern is removed from libgfs2
-void print_it(const char *label, const char *fmt, const char *fmt2, ...) {}
-
-START_TEST(test_lgfs2_meta)
-{
- ck_assert(lgfs2_selfcheck() == 0);
-}
-END_TEST
-
-static Suite * libgfs2_suite(void)
-{
- Suite *s = suite_create("libgfs2");
-
- TCase *tc_meta = tcase_create("Meta");
- tcase_add_test(tc_meta, test_lgfs2_meta);
- suite_add_tcase(s, tc_meta);
-
- return s;
-}
-
-int main(void)
-{
- int failures;
- Suite *s = libgfs2_suite();
- SRunner *sr = srunner_create(s);
- srunner_run_all(sr, CK_NORMAL);
- failures = srunner_ntests_failed(sr);
- srunner_free(sr);
- return failures ? EXIT_FAILURE : EXIT_SUCCESS;
-}
diff --git a/tests/libgfs2.at b/tests/libgfs2.at
deleted file mode 100644
index 3a5174a5..00000000
--- a/tests/libgfs2.at
+++ /dev/null
@@ -1,9 +0,0 @@
-AT_BANNER([libgfs2 unit tests])
-
-GFS_UNIT_TEST([meta.c],[libgfs2])
-AT_CHECK(GFS_RUN_OR_SKIP([check_meta]), 0, [ignore], [ignore])
-AT_CLEANUP
-
-GFS_UNIT_TEST([rgrp.c],[libgfs2])
-AT_CHECK(GFS_RUN_OR_SKIP([check_rgrp]), 0, [ignore], [ignore])
-AT_CLEANUP
diff --git a/tests/testsuite.at b/tests/testsuite.at
index 80bfdda7..98102183 100644
--- a/tests/testsuite.at
+++ b/tests/testsuite.at
@@ -51,4 +51,3 @@ AT_COLOR_TESTS
m4_include([mkfs.at])
m4_include([fsck.at])
m4_include([edit.at])
-m4_include([libgfs2.at])
--
2.26.2
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [Cluster-devel] [PATCH 2/3] Stub out unit tests for the main gfs2-utils
2020-09-11 14:42 [Cluster-devel] [PATCH 0/3] gfs2-utils: Unit test framework improvements Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 1/3] Reorganise unit tests Andrew Price
@ 2020-09-11 14:42 ` Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 3/3] Describe the unit tests in README.tests Andrew Price
2 siblings, 0 replies; 4+ messages in thread
From: Andrew Price @ 2020-09-11 14:42 UTC (permalink / raw)
To: cluster-devel.redhat.com
Create stub unit test infrastructure for mkfs.gfs2, gfs2_edit,
gfs2_convert, tunegfs2, fsck.gfs2, gfs2_jadd and gfs2_grow.
The idea here is to make the effort needed to add unit tests when
writing new code minimal, although with some effort and imagination it
might be possible to make the existing code testable.
main() functions are currently #ifdef'd away when building unit tests as
they clash with the main() function of the unit tests, but a different
method could be used if we find it valuable to test the main() functions
themselves.
Signed-off-by: Andrew Price <anprice@redhat.com>
---
.gitignore | 7 +++++++
gfs2/convert/Makefile.am | 4 ++++
gfs2/convert/check_convert.c | 27 +++++++++++++++++++++++++++
gfs2/convert/checks.am | 7 +++++++
gfs2/convert/gfs2_convert.c | 2 ++
gfs2/edit/Makefile.am | 3 +++
gfs2/edit/check_edit.c | 27 +++++++++++++++++++++++++++
gfs2/edit/checks.am | 7 +++++++
gfs2/edit/hexedit.c | 2 ++
gfs2/fsck/Makefile.am | 4 ++++
gfs2/fsck/check_fsck.c | 27 +++++++++++++++++++++++++++
gfs2/fsck/checks.am | 7 +++++++
gfs2/fsck/main.c | 2 ++
gfs2/mkfs/Makefile.am | 3 +++
gfs2/mkfs/check_grow.c | 27 +++++++++++++++++++++++++++
gfs2/mkfs/check_jadd.c | 27 +++++++++++++++++++++++++++
gfs2/mkfs/check_mkfs.c | 27 +++++++++++++++++++++++++++
gfs2/mkfs/checks.am | 17 +++++++++++++++++
gfs2/mkfs/main_grow.c | 2 ++
gfs2/mkfs/main_jadd.c | 2 ++
gfs2/mkfs/main_mkfs.c | 2 ++
gfs2/tune/Makefile.am | 4 ++++
gfs2/tune/check_tune.c | 27 +++++++++++++++++++++++++++
gfs2/tune/checks.am | 7 +++++++
gfs2/tune/main.c | 2 ++
25 files changed, 273 insertions(+)
create mode 100644 gfs2/convert/check_convert.c
create mode 100644 gfs2/convert/checks.am
create mode 100644 gfs2/edit/check_edit.c
create mode 100644 gfs2/edit/checks.am
create mode 100644 gfs2/fsck/check_fsck.c
create mode 100644 gfs2/fsck/checks.am
create mode 100644 gfs2/mkfs/check_grow.c
create mode 100644 gfs2/mkfs/check_jadd.c
create mode 100644 gfs2/mkfs/check_mkfs.c
create mode 100644 gfs2/mkfs/checks.am
create mode 100644 gfs2/tune/check_tune.c
create mode 100644 gfs2/tune/checks.am
diff --git a/.gitignore b/.gitignore
index 133e8071..74b14b9f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,7 +34,9 @@ cscope.out
*.trs
*.log
gfs2/convert/gfs2_convert
+gfs2/convert/check_convert
gfs2/edit/gfs2_edit
+gfs2/edit/check_edit
gfs2/libgfs2/gfs2l
gfs2/libgfs2/parser.c
gfs2/libgfs2/parser.h
@@ -42,12 +44,17 @@ gfs2/libgfs2/lexer.c
gfs2/libgfs2/lexer.h
gfs2/libgfs2/check_libgfs2
gfs2/fsck/fsck.gfs2
+gfs2/fsck/check_fsck
gfs2/glocktop/glocktop
gfs2/mkfs/mkfs.gfs2
gfs2/mkfs/gfs2_grow
gfs2/mkfs/gfs2_jadd
+gfs2/mkfs/check_grow
+gfs2/mkfs/check_jadd
+gfs2/mkfs/check_mkfs
gfs2/scripts/82-gfs2-withdraw.rules
gfs2/tune/tunegfs2
+gfs2/tune/check_tune
test-driver
tests/nukerg
tests/testvol
diff --git a/gfs2/convert/Makefile.am b/gfs2/convert/Makefile.am
index 2d61af74..2f545909 100644
--- a/gfs2/convert/Makefile.am
+++ b/gfs2/convert/Makefile.am
@@ -10,3 +10,7 @@ gfs2_convert_CPPFLAGS = \
gfs2_convert_LDADD = \
$(top_builddir)/gfs2/libgfs2/libgfs2.la \
$(uuid_LIBS)
+
+if HAVE_CHECK
+include checks.am
+endif
diff --git a/gfs2/convert/check_convert.c b/gfs2/convert/check_convert.c
new file mode 100644
index 00000000..230b9e37
--- /dev/null
+++ b/gfs2/convert/check_convert.c
@@ -0,0 +1,27 @@
+#include <check.h>
+
+START_TEST(test_convert_stub)
+{
+ ck_assert(1);
+}
+END_TEST
+
+static Suite *suite_convert(void)
+{
+ Suite *s = suite_create("gfs2_convert.c");
+ TCase *tc_convert = tcase_create("gfs2_convert");
+ tcase_add_test(tc_convert, test_convert_stub);
+ suite_add_tcase(s, tc_convert);
+ return s;
+}
+
+int main(void)
+{
+ int failures;
+
+ SRunner *runner = srunner_create(suite_convert());
+ srunner_run_all(runner, CK_ENV);
+ failures = srunner_ntests_failed(runner);
+ srunner_free(runner);
+ return failures ? 1 : 0;
+}
diff --git a/gfs2/convert/checks.am b/gfs2/convert/checks.am
new file mode 100644
index 00000000..06a7e3b5
--- /dev/null
+++ b/gfs2/convert/checks.am
@@ -0,0 +1,7 @@
+TESTS = check_convert
+check_PROGRAMS = $(TESTS)
+
+check_convert_SOURCES = $(gfs2_convert_SOURCES) check_convert.c
+check_convert_CPPFLAGS = $(gfs2_convert_CPPFLAGS) -DUNITTESTS
+check_convert_CFLAGS = $(gfs2_convert_CFLAGS) $(check_CFLAGS) -Wno-unused-function
+check_convert_LDADD = $(gfs2_convert_LDADD) $(check_LIBS)
diff --git a/gfs2/convert/gfs2_convert.c b/gfs2/convert/gfs2_convert.c
index 99a9fad8..dd945032 100644
--- a/gfs2/convert/gfs2_convert.c
+++ b/gfs2/convert/gfs2_convert.c
@@ -2160,6 +2160,7 @@ static int gfs2_query(struct gfs2_options *opts, const char *dev)
return res;
}
+#ifndef UNITTESTS
int main(int argc, char **argv)
{
int error;
@@ -2370,3 +2371,4 @@ int main(int argc, char **argv)
free(sd_jindex);
exit(0);
}
+#endif /* UNITTESTS */
diff --git a/gfs2/edit/Makefile.am b/gfs2/edit/Makefile.am
index 53a7dea6..cee327a9 100644
--- a/gfs2/edit/Makefile.am
+++ b/gfs2/edit/Makefile.am
@@ -33,3 +33,6 @@ gfs2_edit_LDADD = \
$(bzip2_LIBS) \
$(uuid_LIBS)
+if HAVE_CHECK
+include checks.am
+endif
diff --git a/gfs2/edit/check_edit.c b/gfs2/edit/check_edit.c
new file mode 100644
index 00000000..1aa7009b
--- /dev/null
+++ b/gfs2/edit/check_edit.c
@@ -0,0 +1,27 @@
+#include <check.h>
+
+START_TEST(test_edit_stub)
+{
+ ck_assert(1);
+}
+END_TEST
+
+static Suite *suite_edit(void)
+{
+ Suite *s = suite_create("hexedit.c");
+ TCase *tc_edit = tcase_create("gfs2_edit");
+ tcase_add_test(tc_edit, test_edit_stub);
+ suite_add_tcase(s, tc_edit);
+ return s;
+}
+
+int main(void)
+{
+ int failures;
+
+ SRunner *runner = srunner_create(suite_edit());
+ srunner_run_all(runner, CK_ENV);
+ failures = srunner_ntests_failed(runner);
+ srunner_free(runner);
+ return failures ? 1 : 0;
+}
diff --git a/gfs2/edit/checks.am b/gfs2/edit/checks.am
new file mode 100644
index 00000000..6d9282a3
--- /dev/null
+++ b/gfs2/edit/checks.am
@@ -0,0 +1,7 @@
+TESTS = check_edit
+check_PROGRAMS = $(TESTS)
+
+check_edit_SOURCES = $(gfs2_edit_SOURCES) check_edit.c
+check_edit_CPPFLAGS = $(gfs2_edit_CPPFLAGS) -DUNITTESTS
+check_edit_CFLAGS = $(gfs2_edit_CFLAGS) $(check_CFLAGS) -Wno-unused-function
+check_edit_LDADD = $(gfs2_edit_LDADD) $(check_LIBS)
diff --git a/gfs2/edit/hexedit.c b/gfs2/edit/hexedit.c
index f8b6f67c..91313e81 100644
--- a/gfs2/edit/hexedit.c
+++ b/gfs2/edit/hexedit.c
@@ -2570,6 +2570,7 @@ static void process_parameters(int argc, char *argv[], int pass)
} /* for */
}/* process_parameters */
+#ifndef UNITTESTS
int main(int argc, char *argv[])
{
int i, j, fd;
@@ -2650,3 +2651,4 @@ int main(int argc, char *argv[])
gfs2_rgrp_free(&sbd, &sbd.rgtree);
exit(EXIT_SUCCESS);
}
+#endif /* UNITTESTS */
diff --git a/gfs2/fsck/Makefile.am b/gfs2/fsck/Makefile.am
index 1c528051..9f0e2035 100644
--- a/gfs2/fsck/Makefile.am
+++ b/gfs2/fsck/Makefile.am
@@ -38,3 +38,7 @@ fsck_gfs2_CPPFLAGS = \
fsck_gfs2_LDADD = \
$(top_builddir)/gfs2/libgfs2/libgfs2.la \
$(uuid_LIBS)
+
+if HAVE_CHECK
+include checks.am
+endif
diff --git a/gfs2/fsck/check_fsck.c b/gfs2/fsck/check_fsck.c
new file mode 100644
index 00000000..08aaee2c
--- /dev/null
+++ b/gfs2/fsck/check_fsck.c
@@ -0,0 +1,27 @@
+#include <check.h>
+
+START_TEST(test_fsck_stub)
+{
+ ck_assert(1);
+}
+END_TEST
+
+static Suite *suite_fsck(void)
+{
+ Suite *s = suite_create("main.c");
+ TCase *tc_fsck = tcase_create("fsck.gfs2");
+ tcase_add_test(tc_fsck, test_fsck_stub);
+ suite_add_tcase(s, tc_fsck);
+ return s;
+}
+
+int main(void)
+{
+ int failures;
+
+ SRunner *runner = srunner_create(suite_fsck());
+ srunner_run_all(runner, CK_ENV);
+ failures = srunner_ntests_failed(runner);
+ srunner_free(runner);
+ return failures ? 1 : 0;
+}
diff --git a/gfs2/fsck/checks.am b/gfs2/fsck/checks.am
new file mode 100644
index 00000000..4e968587
--- /dev/null
+++ b/gfs2/fsck/checks.am
@@ -0,0 +1,7 @@
+TESTS = check_fsck
+check_PROGRAMS = $(TESTS)
+
+check_fsck_SOURCES = $(fsck_gfs2_SOURCES) check_fsck.c
+check_fsck_CPPFLAGS = $(fsck_gfs2_CPPFLAGS) -DUNITTESTS -Wno-unused-const-variable
+check_fsck_CFLAGS = $(fsck_gfs2_CFLAGS) $(check_CFLAGS) -Wno-unused-function
+check_fsck_LDADD = $(fsck_gfs2_LDADD) $(check_LIBS)
diff --git a/gfs2/fsck/main.c b/gfs2/fsck/main.c
index 14cb7d9b..a860f6eb 100644
--- a/gfs2/fsck/main.c
+++ b/gfs2/fsck/main.c
@@ -306,6 +306,7 @@ static void startlog(int argc, char **argv)
free(cmd);
}
+#ifndef UNITTESTS
int main(int argc, char **argv)
{
struct gfs2_sbd sb;
@@ -383,3 +384,4 @@ int main(int argc, char **argv)
}
exit(error);
}
+#endif /* UNITTESTS */
diff --git a/gfs2/mkfs/Makefile.am b/gfs2/mkfs/Makefile.am
index fd7145b8..fd00fdd5 100644
--- a/gfs2/mkfs/Makefile.am
+++ b/gfs2/mkfs/Makefile.am
@@ -50,3 +50,6 @@ gfs2_jadd_LDADD = \
$(top_builddir)/gfs2/libgfs2/libgfs2.la \
$(uuid_LIBS)
+if HAVE_CHECK
+include checks.am
+endif
diff --git a/gfs2/mkfs/check_grow.c b/gfs2/mkfs/check_grow.c
new file mode 100644
index 00000000..d90da2c7
--- /dev/null
+++ b/gfs2/mkfs/check_grow.c
@@ -0,0 +1,27 @@
+#include <check.h>
+
+START_TEST(test_grow_stub)
+{
+ ck_assert(1);
+}
+END_TEST
+
+static Suite *suite_grow(void)
+{
+ Suite *s = suite_create("main_grow.c");
+ TCase *tc_grow = tcase_create("grow.gfs2");
+ tcase_add_test(tc_grow, test_grow_stub);
+ suite_add_tcase(s, tc_grow);
+ return s;
+}
+
+int main(void)
+{
+ int failures;
+
+ SRunner *runner = srunner_create(suite_grow());
+ srunner_run_all(runner, CK_ENV);
+ failures = srunner_ntests_failed(runner);
+ srunner_free(runner);
+ return failures ? 1 : 0;
+}
diff --git a/gfs2/mkfs/check_jadd.c b/gfs2/mkfs/check_jadd.c
new file mode 100644
index 00000000..b692b5a1
--- /dev/null
+++ b/gfs2/mkfs/check_jadd.c
@@ -0,0 +1,27 @@
+#include <check.h>
+
+START_TEST(test_jadd_stub)
+{
+ ck_assert(1);
+}
+END_TEST
+
+static Suite *suite_jadd(void)
+{
+ Suite *s = suite_create("main_jadd.c");
+ TCase *tc_jadd = tcase_create("jadd.gfs2");
+ tcase_add_test(tc_jadd, test_jadd_stub);
+ suite_add_tcase(s, tc_jadd);
+ return s;
+}
+
+int main(void)
+{
+ int failures;
+
+ SRunner *runner = srunner_create(suite_jadd());
+ srunner_run_all(runner, CK_ENV);
+ failures = srunner_ntests_failed(runner);
+ srunner_free(runner);
+ return failures ? 1 : 0;
+}
diff --git a/gfs2/mkfs/check_mkfs.c b/gfs2/mkfs/check_mkfs.c
new file mode 100644
index 00000000..81d91b88
--- /dev/null
+++ b/gfs2/mkfs/check_mkfs.c
@@ -0,0 +1,27 @@
+#include <check.h>
+
+START_TEST(test_mkfs_stub)
+{
+ ck_assert(1);
+}
+END_TEST
+
+static Suite *suite_mkfs(void)
+{
+ Suite *s = suite_create("main_mkfs.c");
+ TCase *tc_mkfs = tcase_create("mkfs.gfs2");
+ tcase_add_test(tc_mkfs, test_mkfs_stub);
+ suite_add_tcase(s, tc_mkfs);
+ return s;
+}
+
+int main(void)
+{
+ int failures;
+
+ SRunner *runner = srunner_create(suite_mkfs());
+ srunner_run_all(runner, CK_ENV);
+ failures = srunner_ntests_failed(runner);
+ srunner_free(runner);
+ return failures ? 1 : 0;
+}
diff --git a/gfs2/mkfs/checks.am b/gfs2/mkfs/checks.am
new file mode 100644
index 00000000..beb03a9b
--- /dev/null
+++ b/gfs2/mkfs/checks.am
@@ -0,0 +1,17 @@
+TESTS = check_grow check_jadd check_mkfs
+check_PROGRAMS = $(TESTS)
+
+check_grow_SOURCES = $(gfs2_grow_SOURCES) check_grow.c
+check_grow_CPPFLAGS = $(gfs2_grow_CPPFLAGS) -DUNITTESTS
+check_grow_CFLAGS = $(gfs2_grow_CFLAGS) $(check_CFLAGS) -Wno-unused-function
+check_grow_LDADD = $(gfs2_grow_LDADD) $(check_LIBS)
+
+check_jadd_SOURCES = $(gfs2_jadd_SOURCES) check_jadd.c
+check_jadd_CPPFLAGS = $(gfs2_jadd_CPPFLAGS) -DUNITTESTS
+check_jadd_CFLAGS = $(gfs2_jadd_CFLAGS) $(check_CFLAGS) -Wno-unused-function
+check_jadd_LDADD = $(gfs2_jadd_LDADD) $(check_LIBS)
+
+check_mkfs_SOURCES = $(mkfs_gfs2_SOURCES) check_mkfs.c
+check_mkfs_CPPFLAGS = $(mkfs_gfs2_CPPFLAGS) -DUNITTESTS
+check_mkfs_CFLAGS = $(mkfs_gfs2_CFLAGS) $(check_CFLAGS) -Wno-unused-function
+check_mkfs_LDADD = $(mkfs_gfs2_LDADD) $(check_LIBS)
diff --git a/gfs2/mkfs/main_grow.c b/gfs2/mkfs/main_grow.c
index 8882ecd3..f527cc82 100644
--- a/gfs2/mkfs/main_grow.c
+++ b/gfs2/mkfs/main_grow.c
@@ -349,6 +349,7 @@ static int open_rindex(char *metafs_path, int mode)
return fd;
}
+#ifndef UNITTESTS
int main(int argc, char *argv[])
{
struct gfs2_sbd sbd, *sdp = &sbd;
@@ -483,3 +484,4 @@ int main(int argc, char *argv[])
log_notice( _("gfs2_grow complete.\n"));
return error;
}
+#endif /* UNITTESTS */
diff --git a/gfs2/mkfs/main_jadd.c b/gfs2/mkfs/main_jadd.c
index b7e9a644..b8f1ad90 100644
--- a/gfs2/mkfs/main_jadd.c
+++ b/gfs2/mkfs/main_jadd.c
@@ -589,6 +589,7 @@ static int check_fit(struct gfs2_sbd *sdp, struct jadd_opts *opts)
return 0;
}
+#ifndef UNITTESTS
int main(int argc, char *argv[])
{
struct jadd_opts opts = {0};
@@ -682,3 +683,4 @@ out:
return ret;
}
+#endif /* UNITTESTS */
diff --git a/gfs2/mkfs/main_mkfs.c b/gfs2/mkfs/main_mkfs.c
index bb9a96d6..0b779593 100644
--- a/gfs2/mkfs/main_mkfs.c
+++ b/gfs2/mkfs/main_mkfs.c
@@ -1038,6 +1038,7 @@ static void open_dev(struct mkfs_dev *dev, int withprobe)
exit(1);
}
+#ifndef UNITTESTS
int main(int argc, char *argv[])
{
struct gfs2_sbd sbd;
@@ -1201,3 +1202,4 @@ int main(int argc, char *argv[])
}
return 0;
}
+#endif /* UNITTESTS */
diff --git a/gfs2/tune/Makefile.am b/gfs2/tune/Makefile.am
index 171377d0..b03f609a 100644
--- a/gfs2/tune/Makefile.am
+++ b/gfs2/tune/Makefile.am
@@ -15,3 +15,7 @@ tunegfs2_CFLAGS = \
$(uuid_CFLAGS)
tunegfs2_LDADD = \
$(uuid_LIBS)
+
+if HAVE_CHECK
+include checks.am
+endif
diff --git a/gfs2/tune/check_tune.c b/gfs2/tune/check_tune.c
new file mode 100644
index 00000000..5bbe5da6
--- /dev/null
+++ b/gfs2/tune/check_tune.c
@@ -0,0 +1,27 @@
+#include <check.h>
+
+START_TEST(test_tune_stub)
+{
+ ck_assert(1);
+}
+END_TEST
+
+static Suite *suite_tune(void)
+{
+ Suite *s = suite_create("main.c");
+ TCase *tc_tune = tcase_create("tunegfs2");
+ tcase_add_test(tc_tune, test_tune_stub);
+ suite_add_tcase(s, tc_tune);
+ return s;
+}
+
+int main(void)
+{
+ int failures;
+
+ SRunner *runner = srunner_create(suite_tune());
+ srunner_run_all(runner, CK_ENV);
+ failures = srunner_ntests_failed(runner);
+ srunner_free(runner);
+ return failures ? 1 : 0;
+}
diff --git a/gfs2/tune/checks.am b/gfs2/tune/checks.am
new file mode 100644
index 00000000..bb644e82
--- /dev/null
+++ b/gfs2/tune/checks.am
@@ -0,0 +1,7 @@
+TESTS = check_tune
+check_PROGRAMS = $(TESTS)
+
+check_tune_SOURCES = $(tunegfs2_SOURCES) check_tune.c
+check_tune_CPPFLAGS = $(tunegfs2_CPPFLAGS) -DUNITTESTS
+check_tune_CFLAGS = $(tunegfs2_CFLAGS) $(check_CFLAGS) -Wno-unused-function
+check_tune_LDADD = $(tunegfs2_LDADD) $(check_LIBS)
diff --git a/gfs2/tune/main.c b/gfs2/tune/main.c
index c1be8bd4..93f0f60c 100644
--- a/gfs2/tune/main.c
+++ b/gfs2/tune/main.c
@@ -62,6 +62,7 @@ static void version(void)
printf("tunegfs2 (%s %s)\n", __DATE__, __TIME__);
}
+#ifndef UNITTESTS
int main(int argc, char **argv)
{
int c, status;
@@ -161,3 +162,4 @@ int main(int argc, char **argv)
out:
return status;
}
+#endif /* UNITTESTS */
--
2.26.2
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [Cluster-devel] [PATCH 3/3] Describe the unit tests in README.tests
2020-09-11 14:42 [Cluster-devel] [PATCH 0/3] gfs2-utils: Unit test framework improvements Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 1/3] Reorganise unit tests Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 2/3] Stub out unit tests for the main gfs2-utils Andrew Price
@ 2020-09-11 14:42 ` Andrew Price
2 siblings, 0 replies; 4+ messages in thread
From: Andrew Price @ 2020-09-11 14:42 UTC (permalink / raw)
To: cluster-devel.redhat.com
Signed-off-by: Andrew Price <anprice@redhat.com>
---
doc/README.tests | 31 +++++++++++++++++++++++++++++--
1 file changed, 29 insertions(+), 2 deletions(-)
diff --git a/doc/README.tests b/doc/README.tests
index 1b90a0c4..292d2ae7 100644
--- a/doc/README.tests
+++ b/doc/README.tests
@@ -23,8 +23,8 @@ tests can be re-run using make check TOPTS='--recheck' although it's better to
re-run the entire suite after fixing tests as a fix for one test could break
another.
-Writing tests
--------------
+Smoke/regression tests
+----------------------
A number of GFS2-specific convenience macros have been defined in testsuite.at
to make defining new tests quick and easy. Also, some variables have been
defined in atlocal.in so that full paths to programs do not have to be included
@@ -55,6 +55,33 @@ be found in the autoconf manual at:
http://www.gnu.org/software/autoconf/manual/index.html
+Unit tests
+----------
+A unit test framework for each of the main utils and libgfs2 is included in its
+source directory. These tests are based on the libcheck C unit test library and
+are built and run by 'make check'. Generally, there should be one check "Suite"
+defined for each source file of the util, named with a check_ prefix,
+containing one or more test cases defined for each externally-visible function.
+For example:
+
+ check_libgfs2 (main file: check_libgfs2.c)
+ |--------Suite: rgrp.c (in check_rgrp.c)
+ | |---------- Test case: test_rbm_find_good
+ | |-----------Test case: test_rbm_find_bad
+ |--------Suite: meta.c (in check_meta.c)
+ | |-----------Test case: test_lgfs2_meta
+ etc. etc.
+
+The build rules for the unit tests are separated into a checks.am file in each
+source directory. Documentation for writing libcheck unit tests can be found
+at:
+
+ https://libcheck.github.io/check/doc/check_html/index.html
+
+Autoconf's automatically generated test driver script only prints one line for
+each unit test executable run instead of one line per test case. To view
+details of unit test failures, see the generated .log and .trs files.
+
Generating coverage reports
---------------------------
Test coverage instrumentation can be enabled using the --enable-gcov option at
--
2.26.2
^ permalink raw reply related [flat|nested] 4+ messages in thread
end of thread, other threads:[~2020-09-11 14:42 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-09-11 14:42 [Cluster-devel] [PATCH 0/3] gfs2-utils: Unit test framework improvements Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 1/3] Reorganise unit tests Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 2/3] Stub out unit tests for the main gfs2-utils Andrew Price
2020-09-11 14:42 ` [Cluster-devel] [PATCH 3/3] Describe the unit tests in README.tests Andrew Price
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.