menuselect: Add menuselect to Asterisk trunk (Patch 1)

This is the first patch that adds menuselect to Asterisk trunk, and removes
the svn:externals property. This is being done for two reasons:
(1) The removal of external repositories eases a future migration to git
(2) Asterisk is now the only thing that uses menuselect; as a result, there's
    little need to keep it in an external repository

Subsequent patches will remove the mxml dependency from menuselect and tidy
up the build system.

ASTERISK-20703


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@418832 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 179 insertions, 0 deletions

diff --git a/menuselect/README b/menuselect/README
new file mode 100644
index 000000000..1a63790b0
--- /dev/null
+++ b/menuselect/README
@@ -0,0 +1,179 @@
+MENUSELECT
+Copyright (C) 2005-2006, Digium, Inc.
+Russell Bryant <russell@digium.com>
+-------------------------------------------------------------------------------
+
+
+ABOUT
+
+Menuselect is a tool designed to be used in conjunction with GNU make. It
+allows for an XML specification of Makefile variables and optional space
+delimited values of these variables. These values can then be used in the
+Makefile to make various decisions during the build process.
+
+Menuselect also provides a mechanism for dependency checking for each possible
+member (value) of each category (Makefile variable). These dependencies are
+generally checked by using autoconf and the results provided to menuselect. If
+dependencies for a member are not met, the user will not be allowed to make
+that selection. In the same way the menuselect does dependency checking, it
+also does conflict checking. If a listed conflict for a member is met, then
+the user will not be allowed to select it.
+
+For use with automated builds or when the user has no desire to make selections
+different than the defined defaults, menuselect can generate a default output
+file for use in the build.
+
+Menuselect can also do a sanity check on existing input files. If any member
+has been selected that has conflicts or unmet dependencies, then menuselect
+will exit with an error and output to notify the user of the situation. This is
+typically done at the beginning of the build process to ensure that given all
+of the known information, the build is going to be successful.
+
+
+MENUSELECT DEPENDENCIES
+
+libncurses -- This is needed for the curses frontend.
+libnewt -- This is needed for the newt frontend (optional).
+libmxml -- This library, Mini-XML, is used for XML parsing. 
+           (http://www.easysw.com/~mike/mxml/)
+	   (Asterisk uses the code in http://svn.digium.com/svn/mxml/ )
+
+
+ENVIRONMENT SETUP
+
+The file menuselect.h contains a couple of defines which specify locations for
+various files.  These locations are relative to the directory from which
+menuselect will be executed.
+
+#define OUTPUT_MAKEOPTS_DEFAULT "menuselect.makeopts"
+This is the location where the menuselect output will be saved.
+
+#define MENUSELECT_DEPS         "build_tools/menuselect-deps"
+This is the location where menuselect will expect to find the input file that
+provides dependency and conflict information. More information on the format of
+this file can be found in the section about dependency and conflict checking.
+
+
+DEPENDENCY AND CONFLICT CHECKING
+
+Members may have as many conflicts and dependencies specified as needed. An
+example of the MENUSELECT_DEPS file would look like this:
+
+DEPENDENCY1=1
+DEPENDENCY2=0
+CONFLICT1=0
+
+In this case, "DEPENDENCY1" has been met, "DEPENDENCY2" has not been met, and
+"CONFLICT1" is not present.
+
+To ask menuselect to do a background sanity check on dependencies and
+conflicts, it can be called like this:
+
+./menuselect --check-deps <input_file1> [input_file2] [...]
+
+The format of the input files must be of the same format menuselect uses to
+create the OUPUT_MAKEOPTS_DEFAULT.
+
+
+ENABLING AND DISABLING OPTIONS FROM THE COMMAND LINE
+
+If you would like menuselect to update choices via the command line, it can be
+done with the following syntax:
+
+Enable an option:
+   $ menuselect/menuselect --enable TEST_FRAMEWORK menuselect.makeopts
+
+Enable all options in a category:
+   $ menuselect/menuselect --enable-category MENUSELECT_TEST menuselect.makeopts
+
+Disable an option:
+   $ menuselect/menuselect --disable TEST_FRAMEWORK menuselect.makeopts
+
+Disable all options in a category:
+   $ menuselect/menuselect --disable-category MENUSELECT_TEST menuselect.makeopts
+
+
+SETTING UP AVAILABLE OPTIONS
+
+The XML specification for the menu lives in the file "menuselect-tree" and should
+be in the same directory that menuselect will be executed from. An example
+menuselect-tree file as used in the Asterisk project (http://www.asterisk.org) is
+provided in example_menuselect-tree
+
+Menu:
+   The top level tag in menuselect-tree is the <menu> tag. All of the categories
+   reside inside of the <menu> ... </menu> block.
+
+Menu Attributes:
+   name="Asterisk Module Selection"
+   This specifies the title of the menu. It is displayed at the top of the
+   screen when using the curses frontend
+
+Categories:
+   A <category> contains members. The category tag can contain a number of
+   different attributes to specify different behavior.
+
+Category Attributes:
+   name="MENUSELECT_APPS"
+   The name attribute is required. This is the name of the variable that will
+   be in the output from menuselect.
+	
+   displayname="Applications"
+   If this is specfied, this is what will be shown in the menu to the user.
+
+   positive_output="yes"
+   The default for menuselect is to output all of the members of a category
+   that are *not* selected. This is because it is often convenient to be able
+   to define a full list in the Makefile and then filter out the results from
+   menuselect. Using GNU make, an example of this would be:
+   APPS:=$(filter-out $(MENUSELECT_APPS),$(APPS)) 
+
+   remove_on_change=".lastclean"
+   This attribute can contain a space delimited list of files to be deleted
+   when it is time to build an output file if any of the members of this
+   category have changed values from their values for existing input when the
+   application was started.
+
+Members:
+   A <member> contains conflicts and dependencies. The member tag can contain a
+   number of different attributes to specify different behavior.
+
+Member Attributes:
+   name="app_meetme"
+   The name attribute is required. This is the value that will be added to the 
+   variable specified by the category when selected (or not selected) depending
+   on the setting of the positive_output attribute of the category.
+	
+   displayname="Call Conferencing Application"
+   If this is specified, this will be provided as a description of this member
+   when the cursor is on it in the menu.
+
+   remove_on_change="apps/app_meetme.o apps/app_meetme.so"
+   This attribute can contain a space delimeted list of files to be deleted
+   when it is time to build an output file if the value of this member has
+   changed from its value in any existing input when the application was
+   started.
+
+Dependencies:
+   A dependency for a <member> is specified using a <depend> tag. The name of
+   the dependency corresponds to names in the MENUSELECT_DEPS file. This is an
+   example of specifying a dependency for a member:
+      <member name="app_meetme">
+         <depend>zaptel</depend>
+      </member>   
+
+Conflicts:
+   A conflict for a <member> is specified using a <conflict> tag. The name of
+   the conflict corresponds to names in the MENUSELECT_DEPS file. This is an
+   example of specifying a dependency for a member:
+      <member name="res_musiconhold">
+         <conflict>win32</conflict>
+      </member>
+
+
+REPORTING BUGS
+
+Any bug reports or feature enhancement submissions to menuselect should be
+submitted at https://issues.asterisk.org/
+
+Thank you!