Feature Marking and Selection - Revision history

Wes: document find-unused-code

2011-05-10T00:07:48Z

document find-unused-code

Wes: /* Coding Using Features Support */ use netsnmp_feature_unused()

2011-05-03T22:53:42Z

‎Coding Using Features Support: use netsnmp_feature_unused()

Wes: /* Checking whether or not a dependent feature is available */

2011-05-03T22:51:25Z

‎Checking whether or not a dependent feature is available

Wes: /* Background */ link to the features page.

2011-03-04T19:18:32Z

‎Background: link to the features page.

Wes: /* Feature Marking and Requiring Macros */ added note about parent/child support

2011-02-01T00:05:56Z

‎Feature Marking and Requiring Macros: added note about parent/child support

Tanders: /* Design Criteria */

2011-01-03T18:51:11Z

‎Design Criteria

Wes: /* Notes on the end result */

2011-01-03T17:34:38Z

‎Notes on the end result

Wes: /* Notes on the end result */

2011-01-03T17:28:38Z

‎Notes on the end result

Wes: /* Behind the Scenes */

2011-01-03T17:28:07Z

‎Behind the Scenes

Wes: /* Checking for Feature Support in Code */

2011-01-03T17:13:26Z

‎Checking for Feature Support in Code

← Older revision		Revision as of 00:07, 10 May 2011
Line 164:		Line 164:

	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.		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.
		+
		+	== Finding Unused Code to Mark as a Feature ==
		+
		+	After building with your favorite set of configure options, you can see how many functions exist in the built .o files using this handy perl script:
		+
		+	perl local/minimalist/find-unused-code -g
		+
		+	Which will produce a list of functions that were compiled but never referenced by another .o file, which indicates they're likely unused. The -g switch will then grep all of the source code for source files that contain calls to those functions. This allows you to know which file contains the function that should be marked as a feature, and which other files need to be modified to netsnmp_feature_require() that function/feature.

@@ Line 95: / Line 95: @@
    #else /* !NETSNMP_FEATURE_REMOVE_FOO */
-   char unused_feature_foo;
+   netsnmp_feature_unused(foo);
    #endif /* !NETSNMP_FEATURE_REMOVE_FOO */
@@ Line 103: / Line 103: @@
 * 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.
+* The netsnmp_feature_unused() macro is only needed if there is no code in the file left after the features have been removed.
 === Checking for Feature Support in Code ===

@@ Line 65: / Line 65: @@
    netsnmp_feature_provide(netsnmpfoo)
    #endif
 ==== Checking whether or not a dependent feature is available ====

← Older revision		Revision as of 19:18, 4 March 2011
Line 4:		Line 4:

	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.		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.
		+
		+	=== Results ===
		+
		+	The current SVN trunk contains code that is marked as described in this document. The resulting feature hierarchy can be found on the [[Features]] page.

	== Design Criteria ==		== Design Criteria ==

← Older revision		Revision as of 00:05, 1 February 2011
Line 30:		Line 30:

	In this case, if ''foo'' is unavailable a hard-error will be triggered. However, if ''bar'' is unavailable the compilation will continue.		In this case, if ''foo'' is unavailable a hard-error will be triggered. However, if ''bar'' is unavailable the compilation will continue.
		+
		+	=== Parent/Child Features ===
		+
		+	To mark a child as being a sub-feature of a parent, use the following macro:
		+
		+	netsnmp_feature_child_of(child,parent)
		+
		+	This will:
		+
		+	# if the child is required:
		+	#* Will turn on the child
		+	#* Will not turn on the parent
		+	# if the parent is required:
		+	#* Will turn on the child
		+	#* Will turn on the parent
		+

	=== Conditionally Requiring and Providing Features ===		=== Conditionally Requiring and Providing Features ===

@@ Line 8: / Line 8: @@
 * 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
+* A configure flag (--with-minimalist) to enable minimal code
 ** --enable-mini-agent should probably turn it on?
 * Flags to request including and excluding of features

← Older revision		Revision as of 17:34, 3 January 2011
Line 112:		Line 112:
	#* But... running '''make cleanfeatures''' first is safer if you're heavily modifying provide/require lines		#* But... running '''make cleanfeatures''' first is safer if you're heavily modifying provide/require lines
	#* Allows for run-time modifications without re-running configure		#* 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.

← Older revision		Revision as of 17:28, 3 January 2011
Line 111:		Line 111:
	# For developers working on feature specific code, '''make''' run from the top level directory will continue to update the generated feature header files		# 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		#* But... running '''make cleanfeatures''' first is safer if you're heavily modifying provide/require lines
		+	#* Allows for run-time modifications without re-running configure

@@ Line 92: / Line 92: @@
 # A set of configure flags to enable ''minimalist'' mode and for selecting and removing specific features, as mentioned previously.
 # 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.
 # 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.

← Older revision		Revision as of 17:13, 3 January 2011
Line 86:		Line 86:
	/* include foo-specific coding here */		/* include foo-specific coding here */
	#endif /* NETSNMP_FEATURE_HAS_FOO */		#endif /* NETSNMP_FEATURE_HAS_FOO */
		+
		+	== Behind the Scenes ==
		+
		+	Behind the scenes, this support is implemented using a number of techniques:
		+
		+	# A set of configure flags to enable ''minimalist'' mode and for selecting and removing specific features, as mentioned previously.
		+	# 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.
		+	# 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.