diff --git a/Makefile b/Makefile index b6c65571..0408ce05 100644 --- a/Makefile +++ b/Makefile @@ -2,6 +2,10 @@ include vars.mk SUBDIRS = include lib bin +ifdef BUILD_API_DOCS +SUBDIRS += doc +endif + .PHONY: all all: @for dir in $(SUBDIRS); do \ diff --git a/README b/README index 2cf0b305..cfedcb28 100644 --- a/README +++ b/README @@ -2,13 +2,17 @@ See http://xbps.nopcode.org/ for information. To build this you'll need: -- openssl (development package with static libs) -- libarchive (development package with static libs, and all features - built in: acl/attr, xz, bzip2 and zlib are REQUIRED to build the - static binaries!) -- proplib (development package with static lib), - available at http://code.google.com/p/portableproplib -- asciidoc (to build the manpages) + - openssl (development package with static libs) + - libarchive (development package with static libs, and all features + built in: acl/attr, xz, bzip2 and zlib are REQUIRED to build the + static binaries!) + - proplib (development package with static lib), + available at http://code.google.com/p/portableproplib + - asciidoc (to build the manpages) + +Optionally to build the API documentation: + + - graphviz and doxygen. By default it will be installed into /usr/local, can be changed by setting PREFIX and DESTDIR vars as make(1) arguments. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..6cf1a3e5 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,24 @@ +# +# Makefile to build the libxbps API documentation. +# +DOXYF ?= xbps_api_doxyfile +FORMAT ?= png +FILES = xbps_transaction_dictionary.$(FORMAT) +FILES += xbps_regpkgdb_dictionary.$(FORMAT) +FILES += xbps_pkg_props_dictionary.$(FORMAT) +FILES += xbps_pkg_files_dictionary.$(FORMAT) +FILES += xbps_binary_pkg_content.$(FORMAT) + +.PHONY: all +all: $(FILES) doxygendocs + +$(FILES): %.$(FORMAT): %.dot + dot -T$(FORMAT) $< -o images/$@ + +doxygendocs: $(FILES) + doxygen $(DOXYF) + +.PHONY: clean +clean: + -rm -f images/*.$(FORMAT) + -rm -rf ../api diff --git a/doc/xbps_api_doxyfile b/doc/xbps_api_doxyfile new file mode 100644 index 00000000..d45d479a --- /dev/null +++ b/doc/xbps_api_doxyfile @@ -0,0 +1,223 @@ +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "The X Binary Package System Library API" +PROJECT_NUMBER = 20100119 +OUTPUT_DIRECTORY = ../api +CREATE_SUBDIRS = YES +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = NO +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = YES +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +EXTENSION_MAPPING = +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +TYPEDEF_HIDES_STRUCT = YES +SYMBOL_CACHE_SIZE = 0 +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = YES +SHOW_INCLUDE_FILES = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = YES +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = YES +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +INPUT = .. +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.c *.h +RECURSIVE = YES +EXCLUDE = ../.bzr ../bin ../lib/fetch \ + ../include/sha256.h ../include/fetch.h +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = .bzr *.mk Makefile +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = images +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = NO +USE_HTAGS = NO +VERBATIM_HEADERS = NO +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_TIMESTAMP = YES +HTML_ALIGN_MEMBERS = NO +HTML_DYNAMIC_SECTIONS = NO +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +USE_INLINE_TREES = NO +TREEVIEW_WIDTH = 250 +FORMULA_FONTSIZE = 10 +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +LATEX_SOURCE_CODE = NO +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +GENERATE_AUTOGEN_DEF = NO +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = SIMPLEQ_ENTRY +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +CLASS_DIAGRAMS = YES +MSCGEN_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +DOT_FONTNAME = DejaVuSansCondensed +DOT_FONTSIZE = 6 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = YES +TEMPLATE_RELATIONS = YES +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = YES +CALLER_GRAPH = YES +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = YES +DOT_MULTI_TARGETS = YES +GENERATE_LEGEND = YES +DOT_CLEANUP = YES diff --git a/doc/xbps_binary_pkg_content.dot b/doc/xbps_binary_pkg_content.dot new file mode 100644 index 00000000..112946cd --- /dev/null +++ b/doc/xbps_binary_pkg_content.dot @@ -0,0 +1,18 @@ +digraph xbps_binary_pkg_content { + graph [ranksep="0"]; + edge [color=white,arrowhead="none",fontname="DejaVuSansCondensed",fontsize="12"]; + node [width="4.0",shape=box,fontname="DejaVuSansCondensed",fontsize="12"]; + install -> remove; + remove -> files_plist; + files_plist -> props_plist; + props_plist -> archive_entry; + archive_entry -> archive_entry2; + archive_entry2 -> archive_entry3; + install [style=filled,label="INSTALL"]; + remove [style=filled,label="REMOVE"]; + files_plist [label="files.plist"]; + props_plist [label="props.plist"]; + archive_entry [style=filled,label="/etc"]; + archive_entry2 [style=filled,label="/etc/foo.conf"]; + archive_entry3 [style=filled,label="..."]; +} diff --git a/doc/xbps_pkg_files_dictionary.dot b/doc/xbps_pkg_files_dictionary.dot new file mode 100644 index 00000000..8968e23f --- /dev/null +++ b/doc/xbps_pkg_files_dictionary.dot @@ -0,0 +1,49 @@ +digraph pkg_files_dictionary { + graph [rankdir=LR,ranksep="0.7"]; + edge [arrowhead="vee",arrowsize="0.2",fontname="DejaVuSansCondensed",fontsize="8"]; + node [height=".1",shape=box,fontname="DejaVuSansCondensed",fontsize="8"]; + files_plist -> main; + files_plist [style=filled,fillcolor=darksalmon,label="files.plist"]; + main [label="Package dictionary"]; + main -> files [label=array]; + files -> files_dict; + files -> files_dict1; + files_dict [style=filled,label="dictionary[0]"]; + files_dict1 [style=filled,label="dictionary[N+1]"]; + files_dict -> file [label=string]; + files_dict -> file_sha256 [label=string]; + file_sha256 [label=sha256]; + files_dict1 -> files_dict1_objs [style=filled,label="objects"]; + files_dict1_objs [style=filled,label="..."]; + main -> conf_files [label=array]; + conf_files [style=filled]; + conf_files -> conf_files_dict; + conf_files -> conf_files_dict1; + conf_files_dict [style=filled,label="dictionary[0]"]; + conf_files_dict1 [style=filled,label="dictionary[N+1]"]; + conf_files_dict -> cf_file [label=string]; + conf_files_dict -> cf_sha256 [label=string]; + conf_files_dict1 -> conf_files_dict1_objs [style=filled,label="objects"]; + conf_files_dict1_objs [style=filled,label="..."]; + cf_file [label=file]; + cf_sha256 [label=sha256]; + conf_files_dict [style=filled]; + main -> links [label=array]; + links -> links_dict; + links -> links_dict1; + links_dict [style=filled,label="dictionary[0]"]; + links_dict1 [style=filled,label="dictionary[N+1]"]; + links_dict -> link_file [label=string]; + link_file [label=file]; + links_dict1 -> links_dict1_objs [style=filled,label="objects"]; + links_dict1_objs [style=filled,label="..."]; + main -> dirs [label=array]; + dirs -> dirs_dict; + dirs -> dirs_dict1; + dirs_dict [style=filled,label="dictionary[0]"]; + dirs_dict1 [style=filled,label="dictionary[N+1]"]; + dirs_dict -> dirs_file [label=string]; + dirs_file [label=file]; + dirs_dict1 -> dirs_dict1_objs [style=filled,label="objects"]; + dirs_dict1_objs [style=filled,label="..."]; +} diff --git a/doc/xbps_pkg_props_dictionary.dot b/doc/xbps_pkg_props_dictionary.dot new file mode 100644 index 00000000..f29cdd41 --- /dev/null +++ b/doc/xbps_pkg_props_dictionary.dot @@ -0,0 +1,37 @@ +digraph pkg_props_dictionary { + graph [rankdir=LR,ranksep="0.7"]; + edge [arrowhead="vee",arrowsize="0.2",fontname="DejaVuSansCondensed",fontsize="8"]; + node [height=".1",shape=box,fontname="DejaVuSansCondensed",fontsize="8"]; + props_plist -> main; + props_plist [style=filled,fillcolor="darksalmon",label="props.plist"]; + main [label="Package dictionary"]; + main -> pkgname [label="string"]; + main -> version [label="string"]; + main -> pkgver [label="string"]; + main -> essential [label="bool"]; + main -> preserve [label="bool"]; + main -> run_depends [label="array"]; + run_depends [style=filled]; + run_depends -> rundep1_string [label="string"]; + run_depends -> rundep2_string [label="string"]; + rundep1_string [label="foo>=1.2"]; + rundep2_string [style=filled,label="..."]; + main -> architecture [label="string"]; + main -> instsize [label="integer"]; + instsize [label="installed_size"]; + main -> short_desc [label="string"] + main -> long_desc [label="string"]; + main -> maintainer [label="string"]; + main -> replaces [label="array"]; + replaces [style=filled]; + replaces -> replace1_string [label="string"]; + replaces -> replace2_string [label="string"]; + replace1_string [label="blah<=2.0"]; + replace2_string [style=filled,label="..."]; + main -> conf_files [label="array"]; + conf_files [style=filled]; + conf_files -> cffile1 [style=filled,label="string"]; + conf_files -> cffile2 [style=filled,label="string"]; + cffile1 [label="/etc/foo.conf"]; + cffile2 [style=filled,label="..."]; +} diff --git a/doc/xbps_regpkgdb_dictionary.dot b/doc/xbps_regpkgdb_dictionary.dot new file mode 100644 index 00000000..0701c6c3 --- /dev/null +++ b/doc/xbps_regpkgdb_dictionary.dot @@ -0,0 +1,34 @@ +digraph regpkgdb_dictionary { + graph [rankdir=LR,rank=same,ranksep=".10"]; + edge [arrowhead="vee",arrowsize="0.2",fontname="DejaVuSansCondensed",fontsize="9"]; + node [height=".1",shape=box,fontname="DejaVuSansCondensed",fontsize="9"]; + regpkgdb_plist -> main; + regpkgdb_plist [style=filled,fillcolor="darksalmon",label="regpkgdb.plist"]; + main [label="Main dictionary"]; + main -> packages [label="array"]; + packages -> pkgdict [label="dictionary"]; + packages -> pkgdict2 [label="dictionary"]; + pkgdict [style=filled,label="Package[0]"]; + pkgdict2 [style=filled,label="Package[N+1]"]; + pkgdict2 -> pkgdict2_objs [label="objects"]; + pkgdict2_objs [style=filled,label="..."]; + pkgdict -> pkgname [label="string"]; + pkgdict -> version [label="string"]; + pkgdict -> pkgver [label="string"]; + pkgdict -> state [label="string"]; + state -> state_inst [label="value"]; + state -> state_cffiles [label="value"]; + state -> state_unpack [label="value"]; + state_inst [style=filled,fillcolor="yellowgreen",label="installed"]; + state_cffiles [style=filled,fillcolor="yellowgreen",label="config-files"]; + state_unpack [style=filled,fillcolor="yellowgreen",label="unpacked"]; + pkgdict -> automatic [label="bool"]; + automatic [label="automatic-install"]; + pkgdict -> short_desc [label="string"] + pkgdict -> requiredby [label="array"]; + requiredby [style=filled]; + requiredby -> reqby1 [label="string"]; + requiredby -> reqby2 [style=filled,label="string"]; + reqby1 [label="blah-2.0"]; + reqby2 [style=filled,label="..."]; +} diff --git a/doc/xbps_transaction_dictionary.dot b/doc/xbps_transaction_dictionary.dot new file mode 100644 index 00000000..c7a618fb --- /dev/null +++ b/doc/xbps_transaction_dictionary.dot @@ -0,0 +1,48 @@ +digraph transaction_dictionary { + graph [rankdir=LR,ranksep=".1"]; + edge [arrowhead="vee",arrowsize="0.40",fontname="DejaVuSansCondensed",fontsize="8"]; + node [shape=box,fontname="DejaVuSansCondensed",fontsize="8",height=".1",width=".1"]; + main -> packages [label="array"]; + main -> missing_deps [label="array"]; + missing_deps -> mdep1 [label="string"]; + missing_deps -> mdep2 [label="string"]; + mdep1 [style=filled,label="blob>=3.0<4.1"]; + mdep2 [style=filled,label="..."]; + main -> totalsize [label="integer"]; + main -> totaldlsize [label="integer"]; + main [style=filled,fillcolor="darksalmon",label="Main dictionary"]; + totalsize [label="total-installed-size"]; + totaldlsize [label="total-download-size"]; + packages -> dictionary [label="dictionary"]; + packages -> dictionary2 [label="dictionary"]; + dictionary [style=filled,label="Package[0]"]; + dictionary2 [style=filled,label="Package[N+1]"]; + dictionary2 -> dict2_objs [label="objects"]; + dict2_objs [style=filled,label="..."]; + dictionary -> pkgname [label="string"]; + dictionary -> version [label="string"]; + dictionary -> pkgver [label="string"]; + dictionary -> run_depends [label="array"]; + run_depends [style=filled]; + run_depends -> rundep1_string [label="string"]; + run_depends -> rundep2_string [label="string"]; + rundep1_string [label="foo>=1.2"]; + rundep2_string [style=filled,label="..."]; + dictionary -> architecture [label="string"]; + dictionary -> filename [label="string"]; + dictionary -> fnamesha256 [label="string"]; + fnamesha256 [label="filename-sha256"]; + dictionary -> fnamesize [label="integer"]; + fnamesize [label="filename-size"]; + dictionary -> instsize [label="integer"]; + instsize [label="installed_size"]; + dictionary -> short_desc [label="string"] + dictionary -> trans_action [label="string"]; + trans_action [label="trans-action"]; + trans_action -> tract_inst [label="value"]; + trans_action -> tract_up [label="value"]; + trans_action -> tract_cf [label="value"]; + tract_inst [style=filled,fillcolor="yellowgreen",label="install"]; + tract_up [style=filled,fillcolor="yellowgreen",label="update"]; + tract_cf [style=filled,fillcolor="yellowgreen",label="configure"]; +} diff --git a/include/mainpage.h b/include/mainpage.h new file mode 100644 index 00000000..70fbda47 --- /dev/null +++ b/include/mainpage.h @@ -0,0 +1,39 @@ +/** + * @mainpage The X Binary Package System Library API + * @section intro_sec Introduction + * + * XBPS is a new binary package system designed and implemented from + * scratch, by Juan Romero Pardines. This document describes + * the API used by the XBPS Library, that is the base to implement + * a package manager frontend, such as is implemented in the xbps-bin(8) + * and xbps-repo(8) command line interfaces. + * + * XBPS uses extensively NetBSD's proplib, a library that provides an + * abstract interface for creating and manipulating property lists. + * Property lists have object types for boolean values, opaque data, numbers, + * and strings. Structure is provided by the array and dictionary collection + * types. Property lists can be passed across protection boundaries by + * translating them to an external representation. This external representation + * is an XML document whose format is described by the following DTD: + * + * http://www.apple.com/DTDs/PropertyList-1.0.dtd + * + * NetBSD's proplib has been choosed because it's fast, extensible, and easy + * to use. These are the three facts I mentioned: + * + * - Fast because proplib uses an ultra optimized + * red-black tree implementation to store and find all its objects, + * the same implementation has been used in commercial projects by + * Apple Inc. + * + * - Extensible because you don't have to worry about ABI problems + * with its objects, arrays and dictionaries can be extended without such + * problems. + * + * - Easy to use (and learn) because it has a superb documentation + * available in the form of manual pages. + * + * Not to mention that its arrays and dictionaries can be externalized to + * files (known as plists) and are always written atomically. You + * have the whole file or don't have it at all. + */ diff --git a/include/xbps_api.h b/include/xbps_api.h index 5621c9a4..735a36c4 100644 --- a/include/xbps_api.h +++ b/include/xbps_api.h @@ -48,44 +48,6 @@ __BEGIN_DECLS /** - * @mainpage The X Binary Package System Library API - * @section intro_sec Introduction - * - * XBPS is a new binary package system designed and implemented from - * scratch, by Juan Romero Pardines. This document describes - * the API used by the XBPS Library, that is the base to implement - * a package manager frontend, such as is implemented in the xbps-bin(8) - * and xbps-repo(8) command line interfaces. - * - * XBPS uses extensively NetBSD's proplib, a library that provides an - * abstract interface for creating and manipulating property lists. - * Property lists have object types for boolean values, opaque data, numbers, - * and strings. Structure is provided by the array and dictionary collection - * types. Property lists can be passed across protection boundaries by - * translating them to an external representation. This external representation - * is an XML document whose format is described by the following DTD: - * - * http://www.apple.com/DTDs/PropertyList-1.0.dtd - * - * NetBSD's proplib has been used because it's fast, extensible, and easy - * to use. These are the three facts I mentioned: - * - * - Fast because proplib uses an ultra optimized - * red-black tree implementation to store and find all its objects, - * the same implementation has been used in commercial projects by - * Apple Inc. - * - * - Extensible because you don't have to worry about ABI problems - * with its objects, arrays and dictionaries can be extended without such - * problems. - * - * - Easy to use (and learn) because it has a superb documentation - * available in the form of manual pages. - * - * Not to mention that its arrays and dictionaries can be externalized to - * files (known as plists) and always are written atomically. You - * have the whole file or don't have it at all. - * * @file include/xbps_api.h * @brief XBPS Library API header * @@ -573,7 +535,7 @@ int xbps_remove_string_from_array(prop_array_t array, const char *str); * * @param[in] pkgname Package name to match. * @param[in] check_state Set it to true to check that package - * is in config-files state. + * is in XBPS_PKG_STATE_CONFIG_FILES state. * * @return 0 on success, or an errno value otherwise. */ @@ -581,7 +543,7 @@ int xbps_purge_pkg(const char *pkgname, bool check_state); /** * Purge all installed packages. Packages that aren't in - * config-files state will be ignored. + * XBPS_PKG_STATE_CONFIG_FILES state will be ignored. * * @return 0 on success, or an errno value otherwise. */ @@ -595,18 +557,19 @@ int xbps_purge_all_pkgs(void); /** * Register a package into the installed packages database. * - * @param[in] pkgrd Package proplib dictionary returned by a transaction. + * @param[in] pkg_dict A dictionary with the following objects: + * \a pkgname, \a version, \a pkgver and \a short_desc (string). * @param[in] automatic Set it to true to mark package that has been * installed by another package, and not explicitly. * * @return 0 on success, an errno value otherwise. */ -int xbps_register_pkg(prop_dictionary_t pkgrd, bool automatic); +int xbps_register_pkg(prop_dictionary_t pkg_dict, bool automatic); /** * Unregister a package from the package database. * - * @param[in] pkgname Package name to match. + * @param[in] pkgname Package name. * * @return 0 on success, an errno value otherwise. */ @@ -618,7 +581,7 @@ int xbps_unregister_pkg(const char *pkgname); /*@{*/ /** - * Initialize resources used by the installed packages database. + * Initialize resources used by the registered packages database. * * @note This function is reference counted, if the database has * been initialized previously, the counter will be increased by one @@ -627,16 +590,16 @@ int xbps_unregister_pkg(const char *pkgname); * @warning Don't forget to always use xbps_regpkgs_dictionary_release() * when its dictionary is no longer needed. * - * @return A proplib dictionary as shown above in the Detailed description - * image on success, or NULL otherwise and errno is set appropiately. + * @return A dictionary as shown above in the Detailed description + * graph on success, or NULL otherwise and errno is set appropiately. */ prop_dictionary_t xbps_regpkgs_dictionary_init(void); /** - * Release resources used by the installed packages database. + * Release resources used by the registered packages database. * * @note This function is reference counted, if the database - * is in use by other callers it won't be released. + * is in use (its reference count number is not 0), won't be released. */ void xbps_regpkgs_dictionary_release(void); @@ -1017,12 +980,12 @@ int xbps_set_pkg_state_dictionary(prop_dictionary_t dict, pkg_state_t state); * * Unpacks a binary package into specified root directory. * - * @param[in] dict Package proplib dictionary as stored in a transaction - * dictionary. + * @param[in] trans_pkg_dict Package proplib dictionary as stored in the + * \a packages array returned by the transaction dictionary. * * @return 0 on success, or an errno value otherwise. */ -int xbps_unpack_binary_pkg(prop_dictionary_t dict); +int xbps_unpack_binary_pkg(prop_dictionary_t trans_pkg_dict); /** @addtogroup util */ /*@{*/ diff --git a/lib/configure.c b/lib/configure.c index af3d800e..0f5027e0 100644 --- a/lib/configure.c +++ b/lib/configure.c @@ -33,16 +33,16 @@ * @brief Package configuration routines * @defgroup configure Package configuration functions * - * Configure a package or all packages. Only packages in unpacked + * Configure a package or all packages. Only packages in XBPS_PKG_STATE_UNPACKED * state will be processed (unless overriden). Package configuration steps: * - Its post-install target in the INSTALL script will be executed. - * - Its state will be changed to installed if previous step + * - Its state will be changed to XBPS_PKG_STATE_INSTALLED if previous step * ran successful. * * @note * If the \a XBPS_FLAG_FORCE is set through xbps_set_flags(), the package - * (or packages) will be reconfigured even if its state is installed, - * as explained in @ref pkgstates. + * (or packages) will be reconfigured even if its state is + * XBPS_PKG_STATE_INSTALLED. */ #include diff --git a/lib/purge.c b/lib/purge.c index d01e946d..ed7e77c6 100644 --- a/lib/purge.c +++ b/lib/purge.c @@ -37,7 +37,7 @@ * @defgroup purge Package purging functions * * These functions will purge an specified package or all packages. - * Only packages in config-files state will be processed + * Only packages in XBPS_PKG_STATE_CONFIG_FILES state will be processed * (unless overriden). Package purging steps: * - Its post-remove target specified in the REMOVE script * will be executed. diff --git a/lib/register.c b/lib/register.c index b6671145..8d753430 100644 --- a/lib/register.c +++ b/lib/register.c @@ -37,23 +37,6 @@ * * Register and unregister packages into/from the installed * packages database. - * - * The following image shows off the full transaction dictionary returned - * by xbps_repository_get_transaction_dict(). The dictionary passed to - * xbps_register_pkg() should be one of those package dictionaries - * stored in the \a packages array stored in the transaction dictionary. - * - * @image html images/xbps_transaction_dictionary.png - * - * Legend: - * - Salmon bg box: The transaction dictionary. - * - White bg box: mandatory objects. - * - Grey bg box: optional objects. - * - Green bg box: possible value set in the object, only one of them - * will be set. - * - * Text inside of white boxes are the key associated with the object, its - * data type is specified on its edge, i.e string, array, integer, dictionary. */ int diff --git a/lib/regpkgs_dictionary.c b/lib/regpkgs_dictionary.c index 93c0a6fd..2837aeeb 100644 --- a/lib/regpkgs_dictionary.c +++ b/lib/regpkgs_dictionary.c @@ -33,26 +33,27 @@ /** * @file lib/regpkgs_dictionary.c - * @brief Installed packages database init/fini routines - * @defgroup regpkgdb Installed packages database init/fini functions + * @brief Package register database routines + * @defgroup regpkgdb Package register database functions * * These functions will initialize and release (resources of) - * the installed packages database. + * the registered packages database plist file (defined by XBPS_REGPKGDB). * - * The returned dictionary by xbps_regpkgs_dictionary_init() (if initialized - * successfully) will have the following structure: + * The returned dictionary by xbps_regpkgs_dictionary_init() uses + * the structure as shown in the next graph: * * @image html images/xbps_regpkgdb_dictionary.png * * Legend: - * - Salmon bg box: XBPS_REGPKGDB_PLIST file internalized. - * - White bg box: mandatory objects. - * - Grey bg box: optional objects. - * - Green bg box: possible value set in the object, only one of them - * will be set. + * - Salmon filled box: \a XBPS_REGPKGDB_PLIST file internalized. + * - White filled box: mandatory objects. + * - Grey filled box: optional objects. + * - Green filled box: possible value set in the object, only one + * of them is set. * * Text inside of white boxes are the key associated with the object, its - * data type is specified on its edge, i.e string, array, integer, dictionary. + * data type is specified on its edge, i.e array, bool, integer, string, + * dictionary. */ static prop_dictionary_t regpkgs_dict; diff --git a/lib/remove.c b/lib/remove.c index c24f44ad..7619710b 100644 --- a/lib/remove.c +++ b/lib/remove.c @@ -39,22 +39,22 @@ * * These functions will remove a package or only a subset of its * files. Package removal steps: - * - Its pre-remove target specified in the REMOVE script - * will be executed. - * - Its files, dirs and links will be removed. Modified files (not - * matching its sha256 hash) will always be preserved. - * - Its post-remove target specified in the REMOVE script - * will be executed. - * - Its requiredby objects will be removed from the installed packages - * database. - * - Its state will be changed to config-files. + * -# Its pre-remove target specified in the REMOVE script + * will be executed. + * -# Its files, dirs and links will be removed. Modified files (not + * matching its sha256 hash) will always be preserved. + * -# Its post-remove target specified in the REMOVE script + * will be executed. + * -# Its requiredby objects will be removed from the installed packages + * database. + * -# Its state will be changed to XBPS_PKG_STATE_CONFIG_FILES. * * @note - * - If a package is going to be updated and it's an essential package, - * only steps 1 and 4 will be executed. - * - If a package is going to be updated and it's NOT an essential - * package, only steps 1, 2 and 4 will be executed. - * - If a package is going to be removed, all steps will be executed. + * -# If a package is going to be updated and it's an essential package, + * only steps 1 and 4 will be executed. + * -# If a package is going to be updated and it's NOT an essential + * package, only steps 1, 2 and 4 will be executed. + * -# If a package is going to be removed, all steps will be executed. * * The following image shows the structure of an internalized package's * files.plist dictionary: diff --git a/vars.mk b/vars.mk index eb63d782..55023a4e 100644 --- a/vars.mk +++ b/vars.mk @@ -8,6 +8,10 @@ MANDIR ?= $(DESTDIR)$(PREFIX)/share/man/man8 TOPDIR ?= .. INSTALL_STRIPPED ?= -s +# To build the libxbps API documentation, requires graphviz and doxygen. +# Uncomment this to enable. +#BUILD_API_DOCS = 1 + LDFLAGS = -L$(TOPDIR)/lib CPPFLAGS = -I$(TOPDIR)/include -D_XOPEN_SOURCE=600 -D_GNU_SOURCE CPPFLAGS += -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -D_LARGE_FILES