asdf-format · embray · Jun 30, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/Makefile.am b/Makefile.am
@@ -105,6 +105,11 @@ asdf_SOURCES = src/main.c
 asdf_CFLAGS = $(AM_CFLAGS) $(FYAML_CFLAGS) $(STATGRAB_CFLAGS) $(LZ4_CFLAGS) $(CODE_COVERAGE_CFLAGS)
 asdf_LDFLAGS = $(CODE_COVERAGE_LDFLAGS)
 asdf_LDADD =  third_party/libstc.la libasdf.la $(ARGP_LIBS) $(ASDF_LIBS)
+
+# The man page is generated from docs/usage/cli.rst with Sphinx but is checked
+# in (see that file) so that building a release tarball does not require Sphinx.
+# dist_man_MANS both distributes it and installs it to $(mandir)/man1.
+dist_man_MANS = docs/man/asdf.1
 endif # ASDF_BUILD_TOOL
 
 

diff --git a/README.rst b/README.rst
@@ -27,6 +27,12 @@ extract binary block data, as well as typed getters for metadata in the ASDF tre
 It also features an extension mechanism (still nascent) for reading ASDF schemas, including
 the core schemas such as ``core/ndarray-<x.y.z>`` into C-native datastructures.
 
+libasdf additionally installs a companion command-line tool, ``asdf``: a wrapper around the
+library providing utilities for inspecting and extracting data from ASDF files.  Its
+capabilities are currently modest but will be expanded in the future; see the
+`command-line tool documentation <https://libasdf.readthedocs.io/en/latest/usage/cli.html>`__
+for details.
+
 Getting Started
 ---------------
 
@@ -292,6 +298,7 @@ Clone the repository and build the project as follows::
     cmake .. \
         -D ENABLE_TESTING=[YES/NO] \
         -D ENABLE_TESTING_SHELL=[YES/NO] \
+        -D ENABLE_TOOL=[YES/NO] \
         -D ENABLE_ASAN=[YES/NO] \
         -D FYAML_NO_PKGCONFIG=[YES/NO] \
             # If YES \
@@ -308,6 +315,25 @@ If doing a system install, as usual it's recommended to install to ``/usr/local`
 by providing ``-DCMAKE_INSTALL_PREFIX=/usr/local`` when running ``cmake``.  Or, if you
 have a ``${HOME}/.local`` you can set the prefix there, etc.
 
+Logging
+^^^^^^^
+
+libasdf can emit diagnostic log messages, controlled by the following options:
+
+- ``-D ENABLE_LOG=[YES/NO]`` -- compile libasdf's internal log statements into
+  the library (default ``YES``).  When ``NO`` they compile to nothing.
+- ``-D ENABLE_LOG_COLOR=[YES/NO]`` -- colorize log output (default ``YES``).
+- ``-D LOG_DEFAULT=LEVEL`` -- the default runtime log level, used when none is
+  set explicitly; one of ``TRACE``, ``DEBUG``, ``INFO``, ``WARN`` (the
+  default), ``ERROR``, ``FATAL``, or ``NONE``.
+- ``-D LOG_MIN=LEVEL`` -- the compile-time minimum level; messages below it are
+  compiled out entirely (default ``TRACE``).
+
+At runtime the default level can also be overridden through the
+``ASDF_LOG_LEVEL`` environment variable.  See the
+`logging documentation <https://libasdf.readthedocs.io/en/latest/usage/opening.html#logging>`__
+for details.
+
 Notes
 ^^^^^
 

diff --git a/cmake/ASDFConfig.cmake b/cmake/ASDFConfig.cmake
@@ -26,10 +26,10 @@ check_include_file(sys/endian.h HAVE_SYS_ENDIAN_H)
 
 if(HAVE_ENDIAN_H)
     set(ENDIAN_H endian.h)
-elseif(HAVE_MACHINE_ENDIAN_H)
-    set(ENDIAN_H machine/endian.h)
 elseif(HAVE_SYS_ENDIAN_H)
     set(ENDIAN_H sys/endian.h)
+elseif(HAVE_MACHINE_ENDIAN_H)
+    set(ENDIAN_H machine/endian.h)
 endif()
 
 macro(check_endian_decl func)

diff --git a/cmake/ASDFDependencies.cmake b/cmake/ASDFDependencies.cmake
@@ -73,7 +73,8 @@ else()
 endif()
 
 
-if(APPLE)
+# argp is only needed by the command-line tool
+if(ENABLE_TOOL AND APPLE)
     option(ARGP_NO_PKGCONFIG NO)
     if(ARGP_NO_PKGCONFIG)
         set(ARGP_LIBRARIES "argp")

diff --git a/cmake/ASDFOptions.cmake b/cmake/ASDFOptions.cmake
@@ -1,16 +1,44 @@
 # Configure options for ASDF library
 include(AddressAnalyzer)
 
-if(ASDF_LOG_ENABLED)
-    option(ASDF_LOG_COLOR "Enable colored log output" ON)
+# Logging (mirrors the Autotools --enable-logging / --enable-log-color /
+# --with-log-default / --with-log-min options)
+set(_ASDF_LOG_LEVELS TRACE DEBUG INFO WARN ERROR FATAL NONE)
+
+# Compile libasdf's own log statements into the library.  When OFF,
+# ASDF_LOG_ENABLED is left undefined and the log statements compile to nothing.
+option(ENABLE_LOG "Compile in libasdf's internal log statements" ON)
+if(ENABLE_LOG)
+    set(ASDF_LOG_ENABLED ON)
+endif()
+
+# Colorized log output
+option(ENABLE_LOG_COLOR "Enable colored log output" ON)
+if(ENABLE_LOG_COLOR)
+    set(ASDF_LOG_COLOR ON)
+endif()
+
+# Default runtime log level: the threshold used when none is set explicitly via
+# asdf_config_t or the ASDF_LOG_LEVEL environment variable.
+set(LOG_DEFAULT WARN CACHE STRING "Default runtime log level (one of ${_ASDF_LOG_LEVELS})")
+if(NOT LOG_DEFAULT IN_LIST _ASDF_LOG_LEVELS)
+    message(FATAL_ERROR "LOG_DEFAULT must be one of: ${_ASDF_LOG_LEVELS}")
 endif()
-set(ASDF_DEFAULT_LOG_LEVEL TRACE CACHE STRING "One of TRACE|DEBUG|INFO|WARN|ERROR|FATAL|NONE")
-set(ASDF_LOG_MIN_LEVEL TRACE CACHE STRING "One of TRACE|DEBUG|INFO|WARN|ERROR|FATAL|NONE")
+
+# Compile-time minimum log level: messages below this level are compiled out.
+set(LOG_MIN TRACE CACHE STRING "Compile-time minimum log level (one of ${_ASDF_LOG_LEVELS})")
+if(NOT LOG_MIN IN_LIST _ASDF_LOG_LEVELS)
+    message(FATAL_ERROR "LOG_MIN must be one of: ${_ASDF_LOG_LEVELS}")
+endif()
+
 set(ASDF_DEBUG OFF CACHE BOOL "Enable DEBUG code")
 
 # Additional feature flags
 option(ENABLE_STATIC "Build as a static library" OFF)
 
+# Build the asdf command-line tool (depends on argp)
+option(ENABLE_TOOL "Build the asdf command-line tool" ON)
+
 # Documentation
 option(ENABLE_DOCS OFF)
 if (ENABLE_DOCS)

diff --git a/config.h.cmake b/config.h.cmake
@@ -2,16 +2,16 @@
 #define CONFIG_H
 
 /* Enable color output in logs */
-#define ASDF_LOG_COLOR @ASDF_LOG_COLOR@
+#cmakedefine ASDF_LOG_COLOR
 
 /* Default runtime log level */
-#define ASDF_LOG_DEFAULT_LEVEL ASDF_LOG_@ASDF_LOG_MIN_LEVEL@
+#define ASDF_LOG_DEFAULT_LEVEL ASDF_LOG_@LOG_DEFAULT@
 
 /* Enable logging */
-#define ASDF_LOG_ENABLED @ASDF_LOG_ENABLED@
+#cmakedefine ASDF_LOG_ENABLED
 
 /* Compile-time minimum log level */
-#define ASDF_LOG_MIN_LEVEL ASDF_LOG_@ASDF_LOG_MIN_LEVEL@
+#define ASDF_LOG_MIN_LEVEL ASDF_LOG_@LOG_MIN@
 
 /* Name of package */
 #define PACKAGE "@PACKAGE_NAME@"

diff --git a/docs/Makefile.am b/docs/Makefile.am
@@ -11,13 +11,17 @@ EXTRA_DIST = \
     api/asdf/error.h.rst \
     api/asdf/extension.h.rst \
     api/asdf/file.h.rst \
+    api/asdf/log.h.rst \
     api/asdf/value.h.rst \
     api/asdf/yaml.h.rst \
     environment.yml \
     index.rst \
     links.rst \
+    usage/cli.rst \
+    usage/compression.rst \
     usage/examples.rst \
     usage/extensions.rst \
+    usage/ndarrays.rst \
     usage/opening.rst \
     usage/overview.rst \
     usage/values.rst \
@@ -26,3 +30,18 @@ EXTRA_DIST = \
     _static/images/favicon.ico \
     _static/images/logo-dark-mode.png \
     _static/images/logo-light-mode.png
+
+
+# Regenerate the checked-in asdf(1) man page from usage/cli.rst.  The man page
+# (man/asdf.1) is committed to the repository so that building a release tarball
+# or installing the tool does not require Sphinx; run this target after editing
+# usage/cli.rst, then commit the updated man/asdf.1.
+if BUILD_DOCS
+man-page: $(srcdir)/man/asdf.1
+
+$(srcdir)/man/asdf.1: $(srcdir)/usage/cli.rst $(srcdir)/conf.py
+	$(SPHINXBUILD) -b man $(srcdir) $(builddir)/_build/man
+	$(MKDIR_P) $(srcdir)/man
+	cp $(builddir)/_build/man/asdf.1 $@
+endif
+.PHONY: man-page
diff --git a/docs/api/asdf/core/datatype.h.rst b/docs/api/asdf/core/datatype.h.rst
@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 asdf/core/datatype.h
 ====================
 

diff --git a/docs/api/asdf/core/ndarray.h.rst b/docs/api/asdf/core/ndarray.h.rst
@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 asdf/core/ndarray.h
 ===================
 

diff --git a/docs/api/asdf/emitter.h.rst b/docs/api/asdf/emitter.h.rst
@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 asdf/emitter.h
 ================
 

diff --git a/docs/api/asdf/error.h.rst b/docs/api/asdf/error.h.rst
@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 asdf/error.h
 ============
 

diff --git a/docs/api/asdf/file.h.rst b/docs/api/asdf/file.h.rst
@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 .. _file.h:
 
 asdf/file.h

diff --git a/docs/api/asdf/log.h.rst b/docs/api/asdf/log.h.rst
@@ -0,0 +1,8 @@
+:tocdepth: 2
+
+.. _log.h:
+
+asdf/log.h
+==========
+
+.. autodoc:: include/asdf/log.h
diff --git a/docs/api/asdf/value.h.rst b/docs/api/asdf/value.h.rst
@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 asdf/value.h
 ============
 

diff --git a/docs/api/asdf/yaml.h.rst b/docs/api/asdf/yaml.h.rst
@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 asdf/yaml.h
 ===========
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -51,7 +51,19 @@ def read_config_h() -> tuple[str, str, str]:
 )]
 
 # -- Options for manual page output --------------------------------------------
-man_pages = [("index", project.lower(), project + " Documentation", [author], 1)]
+# Each tuple is (source doc, name, description, authors, manual section).  The
+# ``asdf`` entry generates an asdf(1) man page from the command-line tool page;
+# build it with ``make man-page`` in this directory.
+man_pages = [
+    ("index", project.lower(), project + " Documentation", [author], 1),
+    (
+        "usage/cli",
+        "asdf",
+        "command-line utility for inspecting and extracting data from ASDF files",
+        [author],
+        1,
+    ),
+]
 
 
 todo_include_todos = True
@@ -108,6 +120,7 @@ def read_config_h() -> tuple[str, str, str]:
     ('c:identifier', 'asdf_history_entry_t'),
     ('c:identifier', 'asdf_parser_cfg_t'),
     ('c:identifier', 'asdf_tag_t'),
+    ('c:identifier', 'asdf_version_t'),
 ]
 
 # Add intersphinx mappings

diff --git a/docs/index.rst b/docs/index.rst
@@ -18,6 +18,8 @@ Usage
   usage/opening
   usage/values
   usage/writing
+  usage/ndarrays
+  usage/compression
   usage/extensions
   usage/examples
 
@@ -44,16 +46,33 @@ Additional less commonly used APIs can be used by including the relevant
 headers.
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 1
 
   api/asdf/emitter.h
   api/asdf/extension.h
+  api/asdf/log.h
   api/asdf/yaml.h
 
 
-.. todo::
+Beyond the high-level `asdf_file_t` interface, libasdf also exposes a
+lower-level, event-based API for streaming through an ASDF file without
+building the whole tree in memory.  It is built around the parser in
+``asdf/parser.h``, which emits a sequence of `asdf_event_t` values (defined in
+``asdf/event.h``), and the corresponding emitter in ``asdf/emitter.h`` for
+writing.  These are intended for advanced use cases and are not yet fully
+documented; most applications should prefer the high-level API described above.
+
+
+Command-line tool
+=================
+
+libasdf installs a companion command-line program, ``asdf``, for inspecting
+and extracting data from ASDF files directly from the shell.
+
+.. toctree::
+  :maxdepth: 2
 
-   Document lower-level APIs.
+  usage/cli
 
 
 Resources