Difference between revisions of "Feature Marking and Selection"

Revision as of 16:55, 3 January 2011

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.

Conditionally Requiring and Providing Features

The feature macros are checked in the output of cpp processing, so typical #ifdef macros can be used to conditionally include or provide features.

Providing a feature only if possible

 To provide conditional support of a feature depending on the output of configure checks:

 #include <net-snmp/net-snmp-config.h>
 #include <net-snmp/features.h>
 
 #ifdef HAVE_FOO_H
 netsnmp_feature_provide(netsnmpfoo)
 #endif

Checking whether or not a dependent feature is available

Sometimes you may wish to advertise support for a feature only if a subordinate feature is also available:

 #include <net-snmp/net-snmp-config.h>
 #include <net-snmp/features.h>
 
 #ifdef NETSNMP_FEATURE_HAS_BAR
 netsnmp_feature_provide(foo)
 #endif /* NETSNMP_FEATURE_HAS_BAR */

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 */