examples: add minimal examples for listing files

.github/workflows/ci.yaml

@@ -21,6 +21,7 @@ jobs:
         apk add zlib-dev lz4-dev xz-dev zstd-dev
         CC=gcc meson setup /tmp/build \
           -Dwerror=true \
+          -Dexamples=true  \
           -Dcurl=enabled  \
           -Dzlib=enabled \
           -Dlz4=enabled \
@@ -74,6 +75,7 @@ jobs:
         meson wrap update-db
         CC=${{ matrix.cc }} meson setup /tmp/build \
           -Dwerror=false \
+          -Dexamples=true \
           -Dcurl=${{ matrix.feature }} \
           -Dzlib=${{ matrix.feature }} \
           -Dlz4=${{ matrix.feature }} \
@@ -100,6 +102,7 @@ jobs:
           sudo pkg_add git meson squashfs-tools curl lz4 xz zstd
           CC=clang meson setup /tmp/build \
             -Dwerror=true \
+            -Dexamples=true \
             -Dcurl=enabled \
             -Dzlib=enabled \
             -Dlz4=enabled \
@@ -129,6 +132,7 @@ jobs:
         git config --global --add safe.directory $PWD
         CC=clang meson setup /tmp/build \
           -Dwerror=true \
+          -Dexamples=true \
           -Dcurl=disabled \
           -Dzlib=disabled \
           -Dlz4=disabled\

Makefile

@@ -21,6 +21,7 @@ else
 	NINJA = ninja
 endif
 MESON_FLAGS += -Ddefault_library=static
+MESON_FLAGS += -Dexamples=true
 MESON_FLAGS += -Db_lundef=false
 #MESON_FLAGS += -Dtest=extended
 MESON_FLAGS += -Dtest=true

doc/Doxyfile.in

@@ -13,7 +13,7 @@ HAVE_DOT              = YES
 DOT_IMAGE_FORMAT      = svg
 INTERACTIVE_SVG       = YES
 FULL_PATH_NAMES       = YES
-STRIP_FROM_PATH       = @DOXYGEN_INPUT@/include/
+STRIP_FROM_PATH       = @DOXYGEN_INPUT@/
 INTERNAL_DOCS         = @DOXYGEN_INTERNAL_DOCS@
 
 # Warning and progress messages
@@ -26,9 +26,9 @@ WARN_AS_ERROR        = YES
 
 
 # Input files
-INPUT         = @DOXYGEN_INPUT@/README.md @DOXYGEN_INPUT@/include @DOXYGEN_INPUT@/doc
+INPUT         = @DOXYGEN_INPUT@/README.md @DOXYGEN_INPUT@/include @DOXYGEN_INPUT@/doc @DOXYGEN_INPUT@/examples
 EXCLUDE       = @DOXYGEN_INPUT@/include/sqsh_data_private.h
-FILE_PATTERNS = *.h *.md
+FILE_PATTERNS = *.c *.h *.md
 EXCLUDE_PATTERNS = *_internal.h
 RECURSIVE     = YES
 USE_MDFILE_AS_MAINPAGE = @DOXYGEN_INPUT@/README.md

examples/list_files.c

@@ -0,0 +1,40 @@
+/**
+ * @author Enno Boland (mail@eboland.de)
+ * @file list_files.c
+ *
+ * This is an example program that lists the top level files in a squashfs
+ * archive.
+ */
+
+#include <assert.h>
+#include <sqsh.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(int argc, char *argv[]) {
+	if (argc != 2) {
+		printf("Usage: %s <sqsh-file>\n", argv[0]);
+		return 1;
+	}
+	struct SqshArchive *archive = sqsh_archive_open(argv[1], NULL);
+	assert(archive != NULL);
+	struct SqshInode *inode = sqsh_open(archive, "/", NULL);
+	assert(inode != NULL);
+	struct SqshDirectoryIterator *iterator =
+			sqsh_directory_iterator_new(inode, NULL);
+	assert(iterator != NULL);
+
+	while (sqsh_directory_iterator_next(iterator) > 0) {
+		/* Use the _dup() variant here because the _name() variant is not
+		 * null-terminated.
+		 */
+		char *name = sqsh_directory_iterator_name_dup(iterator);
+		puts(name);
+		free(name);
+	}
+
+	sqsh_directory_iterator_free(iterator);
+	sqsh_close(inode);
+	sqsh_archive_close(archive);
+}

examples/list_files_ll.c

@@ -0,0 +1,61 @@
+/**
+ * @author Enno Boland (mail@eboland.de)
+ * @file list_files_ll.c
+ *
+ * This is an example program that lists the top level files in a squashfs
+ * archive. It uses low level variants of the API.
+ */
+
+#include <sqsh.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(int argc, char *argv[]) {
+	int error_code = 0;
+	if (argc != 2) {
+		printf("Usage: %s <sqsh-file>\n", argv[0]);
+		return 1;
+	}
+	struct SqshConfig config = {
+		// Read the header file to find documentation on these fields.
+		// It's safe to set them all to 0.
+		.source_mapper = sqsh_mapper_impl_mmap,
+		.source_size = 0,
+		.mapper_block_size = 0,
+		.mapper_lru_size = 0,
+		.compression_lru_size = 0,
+	};
+	struct SqshArchive *archive =
+			sqsh_archive_new(argv[1], &config, &error_code);
+	if (error_code != 0) {
+		sqsh_perror(error_code, "sqsh_archive_new");
+		return 1;
+	}
+	const struct SqshSuperblock *superblock = sqsh_archive_superblock(archive);
+	uint64_t inode_root_ref = sqsh_superblock_inode_root_ref(superblock);
+	struct SqshInode *inode =
+			sqsh_inode_new(archive, inode_root_ref, &error_code);
+	if (error_code != 0) {
+		sqsh_perror(error_code, "sqsh_inode_new");
+		return 1;
+	}
+
+	struct SqshDirectoryIterator *iterator =
+			sqsh_directory_iterator_new(inode, &error_code);
+	if (error_code != 0) {
+		sqsh_perror(error_code, "sqsh_directory_iterator_new");
+		return 1;
+	}
+
+	while (sqsh_directory_iterator_next(iterator) > 0) {
+		const char *name = sqsh_directory_iterator_name(iterator);
+		size_t size = sqsh_directory_iterator_name_size(iterator);
+		fwrite(name, size, 1, stdout);
+		fputc('\n', stdout);
+	}
+
+	sqsh_directory_iterator_free(iterator);
+	sqsh_inode_free(inode);
+	sqsh_archive_close(archive);
+}

examples/meson.build

@@ -0,0 +1,12 @@
+executable(
+    'list_files',
+    'list_files.c',
+    install: false,
+    dependencies: libsqsh_dep,
+)
+executable(
+    'list_files_ll',
+    'list_files_ll.c',
+    install: false,
+    dependencies: libsqsh_dep,
+)

meson.build

@@ -40,6 +40,10 @@ libsqsh_dep = declare_dependency(
     include_directories: libsqsh_include,
 )
 
+if get_option('examples')
+    subdir('examples')
+endif
+
 if get_option('tools')
     subdir('tools')
 endif

meson_options.txt

@@ -28,6 +28,12 @@ option(
     value: 'false',
     description: 'Generate documentation.',
 )
+option(
+    'examples',
+    type: 'boolean',
+    value: false,
+    description: 'Builds usage examples of libsqsh.',
+)
 option(
     'tools',
     type: 'boolean',