documentation, man page

5 files changed, 210 insertions, 33 deletions

diff --git a/docs/source/_static/autodep_arch.png b/docs/source/_static/autodep_arch.png
new file mode 100644
index 0000000..d0bfee9
--- /dev/null
+++ b/docs/source/_static/autodep_arch.png
diff --git a/docs/source/api.rst b/docs/source/api.rst
index 908c3aa..4a0a626 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -1,4 +1,22 @@
-:mod:`API`
-===========================================================================
+***
+API
+***
+
+logfs.fstracer
+==============
+
+.. automodule:: logfs.fstracer
+   :members:
+
+package_utils
+================================
+
+This package contains modules which works with the Portage system
+
+.. automodule:: package_utils.portage_log_parser
+   :members:
+.. automodule:: package_utils.portage_utils
+   :members:
+.. automodule:: package_utils.portage_misc_functions
+   :members:
 
-hello
\ No newline at end of file
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 38e1319..59b55f8 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -2,12 +2,94 @@
 Internals
 *********
 
-hello
+How it works?
+=============
 
-.. automodule:: helpers.colorize_output
-.. autoclass:: color_printer
+Scheme
+------
+.. image:: _static/autodep_arch.png
 
-.. py:function:: enumerate(sequence[, start=0])
+Format of network messages
+--------------------------
 
-   Return an iterator that yields tuples of an index and an item of the
-   *sequence*. (And so on.) 
+
+1. Format of messages to file access registrar::
+
+   <time of event: sec since 1970>
+   <event type: open, read, write>
+   <name of file>
+   <building stage: stagename or unknown>
+   <result:OK,ERR/errno,ASKING,DENIED>
+2. Format of answer for ASKING packet from registrar::
+
+   <ALLOW | DENY>
+
+*Notes:*
+
+* All sockets are SOCK_SEQPACKET
+* All fields are delimited with character with code 0
+
+
+How Hooklib approach works?
+===========================
+
+The main idea of Hooklib approach is to load a dynamic library-hooker 
+**before** any other library(including the C runtime, libc.so). 
+So, the functions, such as open, read and write, executed from this library
+instead of libc.so.
+
+Hooklib module modifies Linux's dynamic linker behavior changing LD_PRELOAD 
+environment variable(see 
+`man 8 ld-linux <http://linux.die.net/man/8/ld-linux>`_ for details).
+Module protects LD_PRELOAD variable from further changes by program.
+
+When hooklib module loads, it connects to file access registrar via Unix domain 
+sockets. If program forks or creates a new thread, another copy of library 
+loads. 
+
+When program do open(...), read(...), write(...), library send an information 
+about a call to registrar. Registar can block or allow an event. If registrer 
+allows an event then the original function is called. Else error 
+"file not found" is returned.
+
+How Fusefs approach works?
+==========================
+
+The main idea if Fusefs approach is to create a loggable filesystem in userspace
+and chroot a program into it.
+
+Before program is launched registrar prepare mounts. It usually do:
+
+1. mount -o bind / /mnt/rootfs/
+2. mount /dev/, /dev/pts, /dev/shm, /proc/, /sys/ same way
+3. mount /lib64/, /lib32/, /var/tmp/portage/ same way to increase performance at 
+   cost of accuracy
+4. launch fuse over /mnt/rootfs/
+
+Fuse module blocks all external access to /mnt/rootfs while program runs.
+
+Fuse module also asks the registrar about event allowness.
+
+*Notes:*
+
+* Checking for allowness takes a much time
+
+Futher analysis of file access events
+=====================================
+
+After file access analyser recieves list of events it maps it on a list of 
+packages. 
+
+Then analyser builds a list of dependencies for packages installed and compares 
+with the list it got from registrar. Analyser believes that packages from system
+profile are implicit dependencies of any package in system.
+
+If dependency from registrar is unexpected simple heuristics used to cut 
+unuseful packages.
+
+Rules of heuristics
+-------------------
+
+1. *Package is not useful if all files are .desktop or .xml or .m4*.
+   Aclocal util tries to read all .m4 files in /usr/share/aclocal directory.
+   Files ending on .desktop and .xml often readed on postrm phase.
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 914ab5a..12fdf8e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,23 +1,7 @@
 # -*- coding: utf-8 -*-
 #
-# Autodep documentation build configuration file, created by
-# sphinx-quickstart on Sat Jul 23 18:33:12 2011.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
 import sys, os
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../../src/autodep'))
-#print os.path.abspath('../../src/autodep')
 
 # -- General configuration -----------------------------------------------------
 
@@ -26,16 +10,14 @@ sys.path.insert(0, os.path.abspath('../../src/autodep'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinx.ext.graphviz']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# The suffix of source filenames.
 source_suffix = '.rst'
 
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
+source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
@@ -104,10 +86,10 @@ html_theme = 'default'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = 'Autodep documentation'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+html_short_title = 'Autodep'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -125,7 +107,7 @@ html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -212,7 +194,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'autodep', u'Autodep Documentation',
+    ('man', 'showfsevents.py', u'auto dependency builder for Gentoo',
      [u'Alexander Bersenev'], 1)
 ]
 
diff --git a/docs/source/man.rst b/docs/source/man.rst
new file mode 100644
index 0000000..ca7fdab
--- /dev/null
+++ b/docs/source/man.rst
@@ -0,0 +1,95 @@
+*************
+USER COMMANDS
+*************
+
+SYNOPSIS
+========
+
+**showfsevents.py** [options] <command>
+
+DESCRIPTION
+===========
+
+Auto dependency builder is a tool for analysis files accessed during 
+building a package. It also can be used for runtime dependencies analysis.
+
+The tool can block an access to files of defined packages.
+
+OPTIONS
+=======
+
+.. program:: showfsevents.py
+
+.. cmdoption:: --help, -h
+
+   show this help message and exit
+
+.. cmdoption:: -b PACKAGES, --block=PACKAGES
+
+   block an access to files from this packages
+
+.. cmdoption:: -f, --files 
+
+   show accessed files and not founded files
+.. cmdoption:: -v, --verbose 
+
+   show non-important packages, show unknown package and unknown stage
+.. cmdoption:: --nocolor, -C
+
+   don't output color
+.. cmdoption:: --hooklib
+
+   use ld_preload logging approach(default)
+.. cmdoption:: --fusefs
+
+   use fuse logging approach(slow, but reliable)
+
+HOOKLIB VS FUSEFS
+=================
+
++------------------------------------------------+-------------+---------------+
+|                                                |   Hooklib   |     Fusefs    |
++================================================+=============+===============+
+| Who can use this approach?                     | **Any user**|   Only root   |
++------------------------------------------------+-------------+---------------+
+| Is approach allows blocking an access to files?|  **YES**    | **YES**       |
++------------------------------------------------+-------------+---------------+
+| Is overhead in performance big?                |  **NO**     | YES [#f1]_    |
++------------------------------------------------+-------------+---------------+
+| What events are logged?                        |  Most [#f2]_| **ALL**       |
++------------------------------------------------+-------------+---------------+
+| When is it recomended to use an approach?      | For analysis| For analysis  |
+|                                                | of          | of *runtime*  |
+|                                                | *buildtime* | dependencies  |
+|                                                | dependencies|               |
++------------------------------------------------+-------------+---------------+
+| Is any pre-requirements for using an approach? | **NO**      | FUSE must be  |
+|                                                |             | enabled in    |
+|                                                |             | kernel        |
++------------------------------------------------+-------------+---------------+
+
+.. rubric:: Notes
+
+.. [#f1] Fuse file system is slower than normal one. Program reads many files 
+   while launching, so this will take more time than usual.
+.. [#f2] Loading of dynamic libraries and direct syscalls will not be logged.
+
+Examples
+========
+
+Get the potential dependencies of a xchat package:
+-----------------------------------------------------
+showfsevents.py emerge xchat
+
+Get the potential dependencies of a xchat package, blocking x11-misc/util-macros package:
+--------------------------------------------------------------------------------------------
+showfsevents.py emerge --block x11-misc/util-macros emerge xchat
+
+Get the potential dependencies of a xchat package, and show files accessed:
+------------------------------------------------------------------------------
+showfsevents.py --files emerge xchat
+
+Get the runtime dependencies of a xchat and show files accessed:
+-------------------------------------------------------------------
+showfsevents.py --fusefs --files xchat
+