Can't find any documentation of libcrun API, nor explanation of what are the "top"-level functions/header files

[phlummox]

The README currently states that

crun aims to be also usable as a library that can be easily included in programs without requiring an external process for managing OCI containers.

However, aside from the fact that there are apparently no developer header files available, I can't even find out what the API for libcrun is. Is there any documentation at all of what functions constitute the intended public-facing parts of the library? I found nothing in the docs directory, and the README doesn't even suggest which header files one might start with, out of the 21 contained in src/libcrun. Running Doxygen over the source to get an idea of the structure didn't seem to help much – every header file seems to refer to almost every other header file, producing dependency graphs like this:

Could you at least mention, in the README, what header files might be useful to look at?

So far, the most helpful file I've found seems to be python/crun_python.c – even though I'm not intending at all to use Python – because it does at least suggest what the "top-level" functions are supposed to be (e.g. libcrun_container_load_from_memory). If the aim is for libcrun to be useful as a library, then perhaps expanding on and documenting the code in python/crun_python.c might be helpful to users?

[phlummox]

One thing that might help external developers help you in documenting the API – if that's something you would be interested in – would be adding an ARCHITECTURE.md file that gives at least a rough idea of what the different files in src/libcrun are for, which ones are at the "bottom" (used by nearly all others), and which ones are at the "top".

I initially thought "container.h" must be near the "top"; but then running Doxygen over the source suggested it's actually near the bottom, because almost every other header file in src/libcrun seems to include "container.h" (.svg file from Doxygen, opening it in a new page should enlarge it):

A rough explanation of what files are doing what might help clarify issues like this.

[giuseppe]

the libcrun API is not in great shape to be used as an external library (despite some efforts to clean it up). There is another issue that is somehow tracking this effort: https://github.com/containers/crun/issues/822

Shortly, the symbols that are supposed to be part of the public API are marked with LIBCRUN_PUBLIC.

I think we should move these symbols in a common header, that is installed, and expect users to include only that.