res_pjsip_session: Allow BYE to be sent on disconnected session.
[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 libxml2 -- This library, the XML C parser and toolkit of Gnome, is used for
38            XML parsing. 
39            (http://xmlsoft.org/)
40
41 ENVIRONMENT SETUP
42
43 The file menuselect.h contains a couple of defines which specify locations for
44 various files.  These locations are relative to the directory from which
45 menuselect will be executed.
46
47 #define OUTPUT_MAKEOPTS_DEFAULT "menuselect.makeopts"
48 This is the location where the menuselect output will be saved.
49
50 #define MENUSELECT_DEPS         "build_tools/menuselect-deps"
51 This is the location where menuselect will expect to find the input file that
52 provides dependency and conflict information. More information on the format of
53 this file can be found in the section about dependency and conflict checking.
54
55
56 DEPENDENCY AND CONFLICT CHECKING
57
58 Members may have as many conflicts and dependencies specified as needed. An
59 example of the MENUSELECT_DEPS file would look like this:
60
61 DEPENDENCY1=1
62 DEPENDENCY2=0
63 CONFLICT1=0
64
65 In this case, "DEPENDENCY1" has been met, "DEPENDENCY2" has not been met, and
66 "CONFLICT1" is not present.
67
68 To ask menuselect to do a background sanity check on dependencies and
69 conflicts, it can be called like this:
70
71 ./menuselect --check-deps <input_file1> [input_file2] [...]
72
73 The format of the input files must be of the same format menuselect uses to
74 create the OUPUT_MAKEOPTS_DEFAULT.
75
76
77 ENABLING AND DISABLING OPTIONS FROM THE COMMAND LINE
78
79 If you would like menuselect to update choices via the command line, it can be
80 done with the following syntax:
81
82 Enable an option:
83    $ menuselect/menuselect --enable TEST_FRAMEWORK menuselect.makeopts
84
85 Enable all options in a category:
86    $ menuselect/menuselect --enable-category MENUSELECT_TEST menuselect.makeopts
87
88 Disable an option:
89    $ menuselect/menuselect --disable TEST_FRAMEWORK menuselect.makeopts
90
91 Disable all options in a category:
92    $ menuselect/menuselect --disable-category MENUSELECT_TEST menuselect.makeopts
93
94
95 SETTING UP AVAILABLE OPTIONS
96
97 The XML specification for the menu lives in the file "menuselect-tree" and should
98 be in the same directory that menuselect will be executed from. An example
99 menuselect-tree file as used in the Asterisk project (http://www.asterisk.org) is
100 provided in example_menuselect-tree
101
102 Menu:
103    The top level tag in menuselect-tree is the <menu> tag. All of the categories
104    reside inside of the <menu> ... </menu> block.
105
106 Menu Attributes:
107    name="Asterisk Module Selection"
108    This specifies the title of the menu. It is displayed at the top of the
109    screen when using the curses frontend
110
111 Categories:
112    A <category> contains members. The category tag can contain a number of
113    different attributes to specify different behavior.
114
115 Category Attributes:
116    name="MENUSELECT_APPS"
117    The name attribute is required. This is the name of the variable that will
118    be in the output from menuselect.
119         
120    displayname="Applications"
121    If this is specfied, this is what will be shown in the menu to the user.
122
123    positive_output="yes"
124    The default for menuselect is to output all of the members of a category
125    that are *not* selected. This is because it is often convenient to be able
126    to define a full list in the Makefile and then filter out the results from
127    menuselect. Using GNU make, an example of this would be:
128    APPS:=$(filter-out $(MENUSELECT_APPS),$(APPS)) 
129
130    remove_on_change=".lastclean"
131    This attribute can contain a space delimited list of files to be deleted
132    when it is time to build an output file if any of the members of this
133    category have changed values from their values for existing input when the
134    application was started.
135
136 Members:
137    A <member> contains conflicts and dependencies. The member tag can contain a
138    number of different attributes to specify different behavior.
139
140 Member Attributes:
141    name="app_meetme"
142    The name attribute is required. This is the value that will be added to the 
143    variable specified by the category when selected (or not selected) depending
144    on the setting of the positive_output attribute of the category.
145         
146    displayname="Call Conferencing Application"
147    If this is specified, this will be provided as a description of this member
148    when the cursor is on it in the menu.
149
150    remove_on_change="apps/app_meetme.o apps/app_meetme.so"
151    This attribute can contain a space delimeted list of files to be deleted
152    when it is time to build an output file if the value of this member has
153    changed from its value in any existing input when the application was
154    started.
155
156 Dependencies:
157    A dependency for a <member> is specified using a <depend> tag. The name of
158    the dependency corresponds to names in the MENUSELECT_DEPS file. This is an
159    example of specifying a dependency for a member:
160       <member name="app_meetme">
161          <depend>zaptel</depend>
162       </member>   
163
164 Conflicts:
165    A conflict for a <member> is specified using a <conflict> tag. The name of
166    the conflict corresponds to names in the MENUSELECT_DEPS file. This is an
167    example of specifying a dependency for a member:
168       <member name="res_musiconhold">
169          <conflict>win32</conflict>
170       </member>
171
172
173 REPORTING BUGS
174
175 Any bug reports or feature enhancement submissions to menuselect should be
176 submitted at https://issues.asterisk.org/
177
178 Thank you!