README 6.8 KB

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