v1_lib_dev_guide

Tony Asleson Gris Ge

LibStorageMgmt Library Developer Guide

This document is assuming you already read the [v1_user_guide].

1. Setup developer environment

    # Grab the code
    $ git clone git://git.code.sf.net/p/libstoragemgmt/code \
        libstoragemgmt-code

    # Change into root of source tree
    $ cd libstoragemgmt-code

    # Make sure build dependencies are installed
    # For EL6 install python-argparse also
    # EPEL7 is needed for perl-Config-IniFiles on RHEL/Centos 7
    $ sudo yum install tar make gcc gcc-c++ libtool autoconf automake \
           yajl-devel pywbem libxml2-devel  check-devel glib2-devel \
           m2crypto libmicrohttpd-devel json-c-devel \
           openssl-devel perl-Config-IniFiles time PyYAML

    # Setup autotools
    $ ./autogen.sh

    # Configure
    $ ./configure

    # Build it
    $ make

    # Link 'lsmenv' to $HOME/bin
    # Assuming libstoragemgmt-code is in "$HOME" and $HOME/bin is in $PATH
    # Check 'lsmenv -h' for detail.
    $ ln -s $HOME/libstoragemgmt-code/tools/lsmenv $HOME/bin/

    # Start lsmd daemon from code tree
    $ lsmenv lsmd

    # Invoke lsmcli command
    $ lsmenv sim lsmcli list --type pools

    # Invoke a interactive python
    $ lsmenv sim python

2. Workflow

            User code(for example: lsmcli)
                        ^
                        |
                        |
                        v
     +------------------+-----------------------+
     |                                          |
   Python API           or                    C API
     |                                          |
     +------------------------------------------+
            |                           ^
            | Initial call              |
            v                           |
    Socket of LSM Daemon                |
            |                           |
            | Invoke and setup          |
            | plugin                    |
            |                           v
            +-------------------> Socket of LSM plugin
                                        ^
                                        |
                                        |
                                        | Storage Vendor SDK
                                        |
                                        v
                                 Storage Array/RAID

The communication between client and LSM daemon/plugin is based on
unix domain socket (default folder is /var/run/lsm/ipc/) and using JSON-RPC for protocol.

3. C Library Code Layout

The C library code is located at 'libstoragemgmt-code/c_binding' folder.
It basicly uses C++ codes internally for data converting between socket JSON
to LSM C API.

TODO: Explain which lib we are using for JSON, socket, and etc.

3.1 c_binding/include/libstoragemgmt

Only 'libstoragemgmt.h' is for client use. (right?).

3.2 c_binding/lsm_datatypes

Explain here what these files (cpp and hpp) for.

3.3 c_binding/lsm_convert

3.4 add more files

4. Python Library Code Layout

The Python libraray code is located at 'libstoragemgmt-code/python_binding'
folder.

4.1 _client.py

This is the sample code of client:

    #!/usr/bin/python2
    import lsm

    lsm_cli_obj = lsm.Client("sim://")      # Make connection.

    pools = lsm_cli_obj.pools()             # Enumerate Storage Pools.

This file is providing the lsm.Client class and its methods.

Some common check also implement here.

4.2 _common.py

This file is providing lsm.ErrorNumber, lsm.LsmError for public client
use.

The Proxy class is for internal use, it make sure all other python exception
is wraped into LsmError.

The 'ErrorLevel' class is not used anywhere. Might be removed in the future.

4.3 _data.py

This file is providing LSM classes defination like lsm.System, lsm.Pool and
etc.

4.4 _iplugin.py

Provide a wrapper class INetworkAttachedStorage, IStorageAreaNetwork,
and INfs to raise LsmError.ErrorNumber.NO_SUPPORT when plugin does not
implement user requested methods.

3.5 _pluginrunner.py

Provide class PluginRunner to server in xxx_lsmplugin.
Please check libstoragemgmt-code/plugin/sim/sim_lsmplugin for detail.

3.6 _transport.py

Used by _client.py to provide communication between plugin and user
application.

3.7 version.py

Generated by autoconf tools for VERSION constant.

4. LSM Daemon Code layout.

The daemon code is located at "libstoragemgmt-code/daemon" folder.

4.1 lsmd -- lsm_daemon.c

Just setup socket and search for plugin.

TODO: explain the workflow with method name.

4.2 lsm_restd

Still in draft stage. Using 'microhttpd.h' for http server, 'json/json.h' for
JSON parsing, 'libxml/uri.h' for URI parsing.

TODO: explain the workflow with method name.

5. How to contribute.

  1. discuss in maillist if it's a new feature or big changes.
  2. work on patches
  3. pep8 or C code style check
  4. make check && make distcheck && make rpm
  5. ask in maillist for help on plugin update and test.
  6. git format patch
  7. git send-email

6. Unit test

TODO: Explain tester.c here.


Related

Wiki: ug
Wiki: v1_user_guide