menuselect: Add menuselect to Asterisk trunk (Patch 1)
[asterisk/asterisk.git] / menuselect / README
1 MENUSELECT
2 Copyright (C) 2005-2006, Digium, Inc.
3 Russell Bryant <russell@digium.com>
4 -------------------------------------------------------------------------------
5
6
7 ABOUT
8
9 Menuselect is a tool designed to be used in conjunction with GNU make. It
10 allows for an XML specification of Makefile variables and optional space
11 delimited values of these variables. These values can then be used in the
12 Makefile to make various decisions during the build process.
13
14 Menuselect also provides a mechanism for dependency checking for each possible
15 member (value) of each category (Makefile variable). These dependencies are
16 generally checked by using autoconf and the results provided to menuselect. If
17 dependencies for a member are not met, the user will not be allowed to make
18 that selection. In the same way the menuselect does dependency checking, it
19 also does conflict checking. If a listed conflict for a member is met, then
20 the user will not be allowed to select it.
21
22 For use with automated builds or when the user has no desire to make selections
23 different than the defined defaults, menuselect can generate a default output
24 file for use in the build.
25
26 Menuselect can also do a sanity check on existing input files. If any member
27 has been selected that has conflicts or unmet dependencies, then menuselect
28 will exit with an error and output to notify the user of the situation. This is
29 typically done at the beginning of the build process to ensure that given all
30 of the known information, the build is going to be successful.
31
32
33 MENUSELECT DEPENDENCIES
34
35 libncurses -- This is needed for the curses frontend.
36 libnewt -- This is needed for the newt frontend (optional).
37 libmxml -- This library, Mini-XML, is used for XML parsing. 
38            (http://www.easysw.com/~mike/mxml/)
39            (Asterisk uses the code in http://svn.digium.com/svn/mxml/ )
40
41
42 ENVIRONMENT SETUP
43
44 The file menuselect.h contains a couple of defines which specify locations for
45 various files.  These locations are relative to the directory from which
46 menuselect will be executed.
47
48 #define OUTPUT_MAKEOPTS_DEFAULT "menuselect.makeopts"
49 This is the location where the menuselect output will be saved.
50
51 #define MENUSELECT_DEPS         "build_tools/menuselect-deps"
52 This is the location where menuselect will expect to find the input file that
53 provides dependency and conflict information. More information on the format of
54 this file can be found in the section about dependency and conflict checking.
55
56
57 DEPENDENCY AND CONFLICT CHECKING
58
59 Members may have as many conflicts and dependencies specified as needed. An
60 example of the MENUSELECT_DEPS file would look like this:
61
62 DEPENDENCY1=1
63 DEPENDENCY2=0
64 CONFLICT1=0
65
66 In this case, "DEPENDENCY1" has been met, "DEPENDENCY2" has not been met, and
67 "CONFLICT1" is not present.
68
69 To ask menuselect to do a background sanity check on dependencies and
70 conflicts, it can be called like this:
71
72 ./menuselect --check-deps <input_file1> [input_file2] [...]
73
74 The format of the input files must be of the same format menuselect uses to
75 create the OUPUT_MAKEOPTS_DEFAULT.
76
77
78 ENABLING AND DISABLING OPTIONS FROM THE COMMAND LINE
79
80 If you would like menuselect to update choices via the command line, it can be
81 done with the following syntax:
82
83 Enable an option:
84    $ menuselect/menuselect --enable TEST_FRAMEWORK menuselect.makeopts
85
86 Enable all options in a category:
87    $ menuselect/menuselect --enable-category MENUSELECT_TEST menuselect.makeopts
88
89 Disable an option:
90    $ menuselect/menuselect --disable TEST_FRAMEWORK menuselect.makeopts
91
92 Disable all options in a category:
93    $ menuselect/menuselect --disable-category MENUSELECT_TEST menuselect.makeopts
94
95
96 SETTING UP AVAILABLE OPTIONS
97
98 The XML specification for the menu lives in the file "menuselect-tree" and should
99 be in the same directory that menuselect will be executed from. An example
100 menuselect-tree file as used in the Asterisk project (http://www.asterisk.org) is
101 provided in example_menuselect-tree
102
103 Menu:
104    The top level tag in menuselect-tree is the <menu> tag. All of the categories
105    reside inside of the <menu> ... </menu> block.
106
107 Menu Attributes:
108    name="Asterisk Module Selection"
109    This specifies the title of the menu. It is displayed at the top of the
110    screen when using the curses frontend
111
112 Categories:
113    A <category> contains members. The category tag can contain a number of
114    different attributes to specify different behavior.
115
116 Category Attributes:
117    name="MENUSELECT_APPS"
118    The name attribute is required. This is the name of the variable that will
119    be in the output from menuselect.
120         
121    displayname="Applications"
122    If this is specfied, this is what will be shown in the menu to the user.
123
124    positive_output="yes"
125    The default for menuselect is to output all of the members of a category
126    that are *not* selected. This is because it is often convenient to be able
127    to define a full list in the Makefile and then filter out the results from
128    menuselect. Using GNU make, an example of this would be:
129    APPS:=$(filter-out $(MENUSELECT_APPS),$(APPS)) 
130
131    remove_on_change=".lastclean"
132    This attribute can contain a space delimited list of files to be deleted
133    when it is time to build an output file if any of the members of this
134    category have changed values from their values for existing input when the
135    application was started.
136
137 Members:
138    A <member> contains conflicts and dependencies. The member tag can contain a
139    number of different attributes to specify different behavior.
140
141 Member Attributes:
142    name="app_meetme"
143    The name attribute is required. This is the value that will be added to the 
144    variable specified by the category when selected (or not selected) depending
145    on the setting of the positive_output attribute of the category.
146         
147    displayname="Call Conferencing Application"
148    If this is specified, this will be provided as a description of this member
149    when the cursor is on it in the menu.
150
151    remove_on_change="apps/app_meetme.o apps/app_meetme.so"
152    This attribute can contain a space delimeted list of files to be deleted
153    when it is time to build an output file if the value of this member has
154    changed from its value in any existing input when the application was
155    started.
156
157 Dependencies:
158    A dependency for a <member> is specified using a <depend> tag. The name of
159    the dependency corresponds to names in the MENUSELECT_DEPS file. This is an
160    example of specifying a dependency for a member:
161       <member name="app_meetme">
162          <depend>zaptel</depend>
163       </member>   
164
165 Conflicts:
166    A conflict for a <member> is specified using a <conflict> tag. The name of
167    the conflict corresponds to names in the MENUSELECT_DEPS file. This is an
168    example of specifying a dependency for a member:
169       <member name="res_musiconhold">
170          <conflict>win32</conflict>
171       </member>
172
173
174 REPORTING BUGS
175
176 Any bug reports or feature enhancement submissions to menuselect should be
177 submitted at https://issues.asterisk.org/
178
179 Thank you!