Feature Marking and Selection

From Net-SNMP Wiki
Revision as of 16:49, 3 January 2011 by Wes (Talk | contribs) (Coding Using Features)

Jump to: navigation, search
Requires Net-SNMP 5.7

Note: Features discussed on this page require Net-SNMP version 5.7 or higher.

Background

Many components of Net-SNMP are present to support certain features in the code. But if the code that requires a feature isn't compiled in, the supporting code still is and needlessly adds to the size of the running executable and libraries.

Design Criteria

  • By default, everything must still be included. 3rd-party developers may be making use of code even if internal Net-SNMP code isn't.
  • A configure flag (--with-minimialist) to enable minimal code
    • --enable-mini-agent should probably turn it on?
  • Flags to request including and excluding of features
    • --with-features="foo bar"
    • --with-out-features="foo bar"

Feature Marking and Requiring Macros

To start with, include <net-snmp/features.h>

 #include <net-snmp/features.h>

If you're implementing code that is only needed in certain locations, declare the feature name using the netsnmp_feature_provide() macro:

 netsnmp_feature_provide(foo)

If the feature is dependent on the availability of another feature, use the netsnmp_feature_require() or netsnmp_feature_want() macros:

 netsnmp_feature_require(foo)
 netsnmp_feature_want(bar)

In this case, if foo is unavailable a hard-error will be triggered. However, if bar is unavailable the compilation will continue.

Coding Using Features Support

To mark code as removable if a feature is unneeded, surround it with #ifndef markings:

 #ifndef NETSNMP_FEATURE_REMOVE_FOO
 /* normal foo code */
 #else /* !NETSNMP_FEATURE_REMOVE_FOO */
 char unused_feature_foo;
 #endif /* !NETSNMP_FEATURE_REMOVE_FOO */

A few important notes:

  • Always use the #ifndef version of checking. If the features.h fails to define anything, the feature will be included by default.
  • Always include the define name in comments after #else and #endif clauses. Later "code-removal" scripts will depend upon it.
  • The char definition is important for avoiding warnings on compilers that complain or refuse to compile empty files.

Checking for Feature Support in Code

If you're writing code that depends on features but isn't "required" (ie, you used netsnmp_feature_want(foo)), then you can test for its support:

 #include <net-snmp/features.h>
 ...
 #ifdef NETSNMP_FEATURE_HAS_FOO
 /* include foo-specific coding here */
 #endif /* NETSNMP_FEATURE_HAS_FOO */