emo/xbps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add infrastructure changes to build the API documentation.

Browse Source 
doxygen and graphviz are required. It's disabled by default, use
the BUILD_API_DOCS make(1) argument to enable it.

--HG--
extra : convert_revision : xtraeme%40gmail.com-20100123013719-pkk3a3823cx09v8l
This commit is contained in:
Juan RP 2010-01-23 02:37:19 +01:00
parent dac80a3fa2
commit 31f821669f
17 changed files with 536 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Makefile
View File

@ -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 \

4
README
View File

@ -10,6 +10,10 @@ To build this you'll need:
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.

24
doc/Makefile Normal file
View File

@ -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

223
doc/xbps_api_doxyfile Normal file
View File

@ -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

18
doc/xbps_binary_pkg_content.dot Normal file
View File

@ -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="..."];
}

49
doc/xbps_pkg_files_dictionary.dot Normal file
View File

@ -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="..."];
}

37
doc/xbps_pkg_props_dictionary.dot Normal file
View File

@ -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="..."];
}

34
doc/xbps_regpkgdb_dictionary.dot Normal file
View File

@ -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="..."];
}

48
doc/xbps_transaction_dictionary.dot Normal file
View File

@ -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"];
}

39
include/mainpage.h Normal file
View File

@ -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 <b>Juan Romero Pardines</b>. 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:
*
* - <b>Fast</b> because proplib uses an ultra optimized
* <em>red-black tree</em> implementation to store and find all its objects,
* the same implementation has been used in commercial projects by
* <em>Apple Inc</em>.
*
* - <b>Extensible</b> because you don't have to worry about ABI problems
* with its objects, arrays and dictionaries can be extended without such
* problems.
*
* - <b>Easy</b> 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 <b>are always written atomically</b>. You
* have the whole file or don't have it at all.
*/

65
include/xbps_api.h
View File

@ -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 <b>Juan Romero Pardines</b>. 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:
*
* - <b>Fast</b> because proplib uses an ultra optimized
* <em>red-black tree</em> implementation to store and find all its objects,
* the same implementation has been used in commercial projects by
* <em>Apple Inc</em>.
*
* - <b>Extensible</b> because you don't have to worry about ABI problems
* with its objects, arrays and dictionaries can be extended without such
* problems.
*
* - <b>Easy</b> 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 <b>always are written atomically</b>. 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 <b>config-files</b> 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
* <b>config-files</b> 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 */
/*@{*/

8
lib/configure.c
View File

@ -33,16 +33,16 @@
* @brief Package configuration routines
* @defgroup configure Package configuration functions
*
* Configure a package or all packages. Only packages in <b>unpacked</b>
* Configure a package or all packages. Only packages in XBPS_PKG_STATE_UNPACKED
* state will be processed (unless overriden). Package configuration steps:
* - Its <b>post-install</b> target in the INSTALL script will be executed.
* - Its state will be changed to <b>installed</b> 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 <b>installed</b>,
* as explained in @ref pkgstates.
* (or packages) will be reconfigured even if its state is
* XBPS_PKG_STATE_INSTALLED.
*/
#include <xbps_api.h>

2
lib/purge.c
View File

@ -37,7 +37,7 @@
* @defgroup purge Package purging functions
*
* These functions will purge an specified package or all packages.
* Only packages in <b>config-files</b> state will be processed
* Only packages in XBPS_PKG_STATE_CONFIG_FILES state will be processed
* (unless overriden). Package purging steps:
* - Its <b>post-remove</b> target specified in the REMOVE script
* will be executed.

17
lib/register.c
View File

@ -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:
* - <b>Salmon bg box</b>: The transaction dictionary.
* - <b>White bg box</b>: mandatory objects.
* - <b>Grey bg box</b>: optional objects.
* - <b>Green bg box</b>: 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

23
lib/regpkgs_dictionary.c
View File

@ -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:
* - <b>Salmon bg box</b>: XBPS_REGPKGDB_PLIST file internalized.
* - <b>White bg box</b>: mandatory objects.
* - <b>Grey bg box</b>: optional objects.
* - <b>Green bg box</b>: possible value set in the object, only one of them
* will be set.
* - <b>Salmon filled box</b>: \a XBPS_REGPKGDB_PLIST file internalized.
* - <b>White filled box</b>: mandatory objects.
* - <b>Grey filled box</b>: optional objects.
* - <b>Green filled box</b>: 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;

16
lib/remove.c
View File

@ -39,22 +39,22 @@
*
* These functions will remove a package or only a subset of its
* files. Package removal steps:
* - Its <b>pre-remove</b> target specified in the REMOVE script
* -# Its <b>pre-remove</b> target specified in the REMOVE script
* will be executed.
* - Its files, dirs and links will be removed. Modified files (not
* -# Its files, dirs and links will be removed. Modified files (not
* matching its sha256 hash) will always be preserved.
* - Its <b>post-remove</b> target specified in the REMOVE script
* -# Its <b>post-remove</b> target specified in the REMOVE script
* will be executed.
* - Its requiredby objects will be removed from the installed packages
* -# Its requiredby objects will be removed from the installed packages
* database.
* - Its state will be changed to <b>config-files</b>.
* -# 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,
* -# If a package is going to be updated and it's an essential package,
* only steps <b>1</b> and <b>4</b> will be executed.
* - If a package is going to be updated and it's <b>NOT</b> an essential
* -# If a package is going to be updated and it's <b>NOT</b> an essential
* package, only steps <b>1</b>, <b>2</b> and <b>4</b> will be executed.
* - If a package is going to be removed, all steps 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:

4
vars.mk
View File

@ -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