Difference between revisions of "Feature Marking and Selection"

Revision as of 17:34, 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 */

Behind the Scenes

Behind the scenes, this support is implemented using a number of techniques:

1. A set of configure flags to enable minimalist mode and for selecting and removing specific features, as mentioned previously.
2. When --with-minimalist is turned on, it adds an extra step to the compilation process: features which performs the rest of the steps below:
3. Compile-time feature-check and feature-remove scripts that:
   • feature-check: examines a code file for netsnmp_feature_XXX() lines and creates #define statements based on what it finds.
     • Requires that the code be examined in reverse order (eg, agent/mibgroup/ before agent/helpers/ and both before snmplib/).
   • feature-remove: examines the results of the feature-check output and creates .h files specific to individual code sections with NETSNMP_FEATURE_REMOVE_XXX definitions or NETSNMP_FEATURE_HAS_XXX definitions.
     • Includes a feature if anything requires or wants it
     • Removes a feature if nothing requires it
     • Removes a feature if something wants it, but --with-out-features requested it to be removed
     • Includes a feature if nothing required or wanted it but --with-features requested it
4. A Net-SNMP/features.h file that "does the right thing".
   • During the run of feature-check it includes the definitions being produced by the checking
   • During compilation time, it includes the various feature.h files that has the NETSNMP_FEATURE_REMOVE_XXX and NETSNMP_FEATURE_HAS_XXX tokens.

Notes on the end result

1. ./configure ; make ; make install still works
2. ./configure --with-minimalist ; make ; make install works
3. For developers working on feature specific code, make run from the top level directory will continue to update the generated feature header files
   • But... running make cleanfeatures first is safer if you're heavily modifying provide/require lines
   • Allows for run-time modifications without re-running configure

Real World Examples

TLS/DTLS

In the new DTLS and TLS code we require a significant amount of certificate code. Code is needed to manipulate certificate chains, load and unload directories of certificates, etc. This code is contained in snmplib/cert_util.c.

To only include this code support when needed, snmplib/cert_util.c has the following code:

 #include <net-snmp/features.h>
 
 netsnmp_feature_provide(cert_util)
 
 #ifndef NETSNMP_FEATURE_REMOVE_CERT_UTIL
 /* ... */
 #endif /* NETSNMP_FEATURE_REMOVE_CERT_UTIL */

And in the snmplib/transports/snmpTLSTCPDomain.c and snmplib/transports/snmpDTLSUDPDomain.c file:

 #include <net-snmp/features.h>
 
 netsnmp_feature_require(cert_util)

The end result is that if a user is not requiring the DTLS or TLS support and they've requested --enable-minimalist then the entire cert_util.c functionality is not included. This is actually a very significant chunk of code.