OpenDRIM Linux Management Providers (LMPs) development guidelines

It is assumed the reader has knowledge about the CIM/WBEM architecture of the DMTF (http://www.dmtf.org). If it is not the case it is strongly recommended to learn more about this architecture before going on reading this document.

1. Packaging

This part contains the guidelines for the packaging of the source code of a Linux Management Provider (LMP) package. Note that we are using the OpenDRIM Provider Code Generator whose output complies with these guidelines. A package MAY be written from scratch but using the OpenDRIM Provider Code Generator is strongly recommended. Please refer to the OpenDRIM PACKAGENAME provider package to have a better idea on the format of the files a provider package contains.

1.1. General features

The Linux Management Providers are written in C++ and they implement the CMPI (Common Manageability Provider Interface) provider interface. All the Linux Management Provider packages are dependent on the OpenDRIM Common Library?. The Linux Management Providers are packaged with the autoconf, automake and libtool GNU tools. The Linux Management Providers can be installed against the OpenPegasus, OpenWBEM and SBLIM sfcb CIM servers. Refer to the CIM server installation guidelines for how to install the CIM server of your choice.

1.2. Dependencies

1.2.1. For packaging

• autoconf (2.57 and upper): http://www.gnu.org/software/autoconf

• automake (1.5 and upper): http://www.gnu.org/software/automake

• libtool (1.8.5 and upper): http://www.gnu.org/software/libtool

1.2.1. For compiling

• GCC (3.2.0 and upper)

• CMPI headers: cmpidt.h, cmpimacs.h (CMPI version 1.0 and upper)

• OpenDRIM common headers (provided by the Common Library Package): Common.h, Transtype.h, CMPIBroking.h, Instance.h, Objectpath.h, Association.h, Indication.h (OpenDRIM Common Library? 1.0.0 and upper)

The CMPI headers should be provided along with the CIM server of your choice.

1.2.2. For running

• OpenDRIM Common Library: libOpenDRIMCommon.so (OpenDRIM Common Library? 1.0.0 and upper)

• CIM Server: OpenPegasus (version 2.5.2 and upper with CIM schema version 2.14 and upper) OR OpenWBEM (version 3.2.2 and upper) OR SBLIM sfcb (version 1.1.0 or upper)

1.3. Package architecture

Conventions for the following sections:

• <packagename>: The name of a Linux Management Provider Package
• <classnameX>: The name of a CIM Class, also being the name of a provider (one CIM Class <=> one provider)

A package is set of providers. For clarity we define the following rules:

• One provider implements one and only one CIM Class;
• The code of one provider compiles in one and only one provider library;
• A package may contain one or more providers if they cover the same management area (regrouping in a same package aims to create synergies).

Note: When registering to a CIM server the providers are regrouped into modules. The notion of module and the notion of package are different. In our template, one library corresponds to one module, which corresponds to one CIM Class. A package may contain more than one provider.

1.3.1. Organization of the source code of a provider

The source code of one provider MUST be organized as follow:

File path	Content
<packagename>/<classname>/<classname>.h	Declaration and definition of the User-Friendly class
<packagename>/<classname>/cmpi<classname>.h	Declaration of the “User-Friendly instance to CMPI object” and “CMPI object to User-Friendly instance” conversion functions
<packagename>/<classname>/cmpi<classname>.cpp	Definition of the “User-Friendly instance to CMPI object” and “CMPI object to User-Friendly instance” conversion functions
<packagename>/<classname>/<classname>Access.h	Declaration of the Resource Access functions
<packagename>/<classname>/<classname>Access.cpp	Definition of the Resource Access functions
<packagename>/<classname>/<classname>Provider.cpp	Implementation of the CMPI interface
<packagename>/<classname>/assoc<classname>.cpp	Declaration of the Instances Retrieval functions
<packagename>/<classname>/assoc<classname>.cpp	Definition of the Instances Retrieval functions
<packagename>/<classname>/Makefile.am	Build script entries for automake

The User-Friendly class is a representation in C++ of the CIM Class this provider instruments. The instances created from this class are converted in CIM Instances / CIM ObjectPaths during the execution of the provider code.

The Resource Access functions:

• Gather the information about the Managed Elements and fill in the User-Friendly instances (enumeration of the name or content of the instances, retrieval of the content of an instance);
• Modify the Managed Elements (create or delete instances, modification of the content of an instance);
• Perform an action on a Managed Element (invocation of an extrinsic method).

The Instances Retrieval functions (association only):

• Enumerate/Get the Instances that may be associated (CMPI Broker OR Direct Invocation).
• See section 1.3.7. Direct Invocation for more details

A Linux Management Providers developer SHOULD only create or modify the Resource Access functions.

1.3.2. Organization of the source code of the package common library

File path	Content
<packagename>/Common/<packagename>_Common.h	Declaration of the classes, structures and functions of the common utilities
<packagename>/Common/<packagename>_Common.cpp	Definition of the classes, structures and functions of the common utilities
<packagename>/Common/Makefile.am	Build script entries for automake

The common utilities regroup code which is shared by the providers of a package.

1.3.3. Organization of the CIM mof code

File path	Content
<packagename>/mof/<packagename>.mof	File regrouping the mof files of the CIM Classes of this package (as includes directives)
<packagename>/mof/<classnameX>.mof	Declaration of the CIM Class <classnameX> in mof code

1.3.4. Organization of the provider registration scripts

File path	Content
<packagename>/registration/<packagename>.sh	Script registering all the provider of the package against the CIM server
<packagename>/registration/<packagename>-remove.sh	Script un-registering all the provider of the package against the CIM server
<packagename>/registration/<classnameX>.sh	Script registering the provider <classnameX> against the CIM server
<packagename>/registration/<classnameX>-remove.sh	Script un-registering the provider <classnameX> against the CIM server

1.3.5. Organization of the test routines

File path	Content
<packagename>/test/test-<classnameX>.cpp	Offline tests for the enumeration and retrieval of instances (Do not require a CIM Server)
<packagename>/test/Makefile.am	Build script entry for automake

1.3.6. Organization of the package common files

File path	Content
<packagename>/configure.ac	Configure script entry for autoconf in M4
<packagename>/acinclude.m4	Macro definition written in M4 (used by autoconf)
<packagename>/Makefile.am	Build script entries for automake
<packagename>/AUTHORS	Information about the authors
<packagename>/INSTALL	Information on how to install the package
<packagename>/NEWS	Information on changes
<packagename>/README	General information about the package
<packagename>/TODO	List of TODOs for this package
<packagename>/VERSION	Current version of the package
<packagename>/COPYING	A copy of the license of the package
<packagename>/mof.generation	A directory containing the mof file(s) used for the generation of the provider code
<packagename>/documentation	A directory containing various documents about the package

1.3.7. Direct Invocation

// TODO

1.3.8. Data Store

// TODO

1.3.9. Sample directory structure

1.3.10. Licensing

The Linux Management Providers are released under the GPL license. Each package is provided with a copy of the GPL license (COPYING). Each source file and important script files MUST contain a header specifying the licensing as follow:

• configure.ac:

# Process this file with autoconf to produce a configure script.

#################################################################################
# Linux Management Providers (LMP), <Packagename> provider package
# Copyright (C) 2007 <Author(s)>, <Affiliation> <e-mails>
# 
# This program is being developed under the "OpenDRIM" project.
# The "OpenDRIM" project web page: www.opendrim.org
# The "OpenDRIM" project mailing list: opendrim@googlegroups.com
# 
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; version 2
# of the License.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#################################################################################

#################################################################################
# To contributors, please leave your contact information in this section
# AND comment your changes in the source code.
# 
# Modified by <Author(s)>, <Affiliation>, <Year>
#################################################################################

AC_PREREQ(2.59)
AC_COPYRIGHT([[###############################################################################
Note: This Copyright statement covers the OpenDRIM original parts of this file.
It does NOT concern the parts generated by autoconf.
Linux Management Providers (LMP), <Packagename> provider package
Copyright (C) 2007 <Author(s)>, <Affiliation> <e-mails>

This program is being developed under the "OpenDRIM" project.
The "OpenDRIM" project web page: www.opendrim.org
The "OpenDRIM" project mailing list: opendrim@googlegroups.com

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; version 2
of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
###############################################################################]])

• acinclude.m4:

#################################################################################
# Linux Management Providers (LMP), <Packagename> provider package
# Copyright (C) 2007 <Author(s)>, <Affiliation> <e-mails>
# 
# This program is being developed under the "OpenDRIM" project.
# The "OpenDRIM" project web page: www.opendrim.org
# The "OpenDRIM" project mailing list: opendrim@googlegroups.com
# 
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; version 2
# of the License.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#################################################################################

#################################################################################
# To contributors, please leave your contact information in this section
# AND comment your changes in the source code.
# 
# Modified by <Author(s)>, <Affiliation>, <Year>
#################################################################################

AC_DEFUN([SHOW_COPYRIGHT],
	[
        echo "#################################################################################
# Linux Management Providers (LMP), <Packagename> provider package
# Copyright (C) 2007 <Author(s)>, <Affiliation> <e-mails>
# 
# This program is being developed under the "OpenDRIM" project.
# The "OpenDRIM" project web page: www.opendrim.org
# The "OpenDRIM" project mailing list: opendrim@googlegroups.com
# 
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; version 2
# of the License.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#################################################################################
"
	]
)

• Makefile.am:

#################################################################################
# Note: This Copyright statement covers the OpenDRIM original parts of this file.
# It does NOT concern the parts generated by automake.
# 
# Linux Management Providers (LMP), <Packagename> provider package
# Copyright (C) 2007 <Author(s)>, <Affiliation> <e-mails>
# 
# This program is being developed under the "OpenDRIM" project.
# The "OpenDRIM" project web page: www.opendrim.org
# The "OpenDRIM" project mailing list: opendrim@googlegroups.com
# 
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; version 2
# of the License.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#################################################################################

#################################################################################
# To contributors, please leave your contact information in this section
# AND comment your changes in the source code.
# 
# Modified by <Author(s)>, <Affiliation>, <Year>
#################################################################################

• Text files, scripts (bash):

#################################################################################
# Linux Management Providers (LMP), <Packagename> provider package
# Copyright (C) 2007 <Author(s)>, <Affiliation> <e-mails>
# 
# This program is being developed under the "OpenDRIM" project.
# The "OpenDRIM" project web page: www.opendrim.org
# The "OpenDRIM" project mailing list: opendrim@googlegroups.com
# 
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; version 2
# of the License.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#################################################################################

#################################################################################
# To contributors, please leave your contact information in this section
# AND comment your changes in the source code.
# 
# Modified by <Author(s)>, <Affiliation>, <Year>
#################################################################################

• C++ files (.h, .cpp):

/*################################################################################
# Linux Management Providers (LMP), <Packagename> provider package
# Copyright (C) 2007 <Author(s)>, <Affiliation> <e-mails>
# 
# This program is being developed under the "OpenDRIM" project.
# The "OpenDRIM" project web page: www.opendrim.org
# The "OpenDRIM" project mailing list: opendrim@googlegroups.com
# 
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; version 2
# of the License.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#################################################################################

#################################################################################
# To contributors, please leave your contact information in this section
# AND comment your changes in the source code.
# 
# Modified by <Author(s)>, <Affiliation>, <Year>
###############################################################################*/

• mof files:

//################################################################################
// Linux Management Providers (LMP), <Packagename> provider package
// Copyright (C) 2007 <Author(s)>, <Affiliation> <e-mails>
// 
// This program is being developed under the "OpenDRIM" project.
// The "OpenDRIM" project web page: www.opendrim.org
// The "OpenDRIM" project mailing list: opendrim@googlegroups.com
// 
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// as published by the Free Software Foundation; version 2
// of the License.
// 
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
//################################################################################

//################################################################################
// To contributors, please leave your contact information in this section
// AND comment your changes in the source code.
// 
// Modified by <Author(s)>, <Affiliation>, <Year>
//##############################################################################*/

2. Developing Provider Code

2.1. From scratch

• Follow strictly the package architecture described in part 1.
• If you develop providers on the behalf of the OpenDRIM project you MUST respect the OpenDRIM licensing by applying the GPL license as described in section 1.3.7.

2.2. Modifying existing provider code

• Your modifications MUST not alter the packaging itself (the modified package MUST comply with the package architecture described in part 1).
• You MAY add new files at the condition they are placed logically in the package architecture (example: new source files implementing features of a specific provider (specific CIM Class <classname>) should be placed under the <packagename>/<classname> directory).
• In each existing file, right after the licensing statement, there is a section concerning the modification of content of the file (see section 1.3.7). As it says, the modifiers MUST leave information about themselves in this section. Additionally a modifier MUST place some comments directly in the source code, right before the modification(s), indicating his name and the reason why he did this (these) modification(s).
• Additions to existing file(s) are considered as a modification of this (these) file(s) and therefore MUST be proceeded in the same manner.

2.3. GNU auto tools

• The Linux Management Providers are packaged using autoconf, automake and libtool.
• From configure.ac, acinclude.m4 and the Makefile.am files the GNU auto tools generate many other files which are not described in this document. The developer should know that after modifying one of the previous files he MUST execute the following command in order to update the generated Makefiles, configure script, etc.:
  • $ autoreconf --install
• A developer MUST NOT modify any other file than those described in this document. He MUST NOT modify the files generated by the GNU auto tools.

2007/02/07 Frederic Desmons, desmons@etri.re.kr