1 /*
   2  * Miscellaneous instructions for building and using the iASL compiler.
   3  */
   4 Last update 9 December 2013.
   5 
   6 
   7 1) Generating iASL from source
   8 ------------------------------
   9 
  10 Generation of the ASL compiler from source code requires these items:
  11 
  12     1) The ACPICA source code tree.
  13     2) An ANSI C compiler.
  14     3) The Flex (or Lex) lexical analyzer generator.
  15     4) The Bison (or Yacc) parser generator.
  16 
  17 There are three major ACPICA source code components that are required to
  18 generate the compiler (Basically, the entire ACPICA source tree should
  19 be installed):
  20 
  21     1) The ASL compiler source.
  22     2) The ACPICA Core Subsystem source. In particular, the Namespace
  23         Manager component is used to create an internal ACPI namespace
  24         and symbol table, and the AML Interpreter is used to evaluate
  25         constant expressions.
  26     3) The "common" source directory that is used for all ACPI components.
  27 
  28 
  29 1a) Notes for Linux/Unix generation
  30 -----------------------------------
  31 
  32 iASL has been generated with these versions of Flex/Bison:
  33 
  34     flex:  Version 2.5.32
  35     bison: Version 2.6.2
  36 
  37 Other required packages:
  38 
  39     make
  40     gcc C compiler
  41     m4 (macro processor required by bison)
  42 
  43 On Linux/Unix systems, the following commands will build the compiler:
  44 
  45     cd acpica (or cd acpica/generate/unix)
  46     make clean
  47     make iasl
  48 
  49 
  50 1b) Notes for Windows generation
  51 --------------------------------
  52 
  53 On Windows, the Visual Studio 2008 project file appears in this directory:
  54 
  55     generate/msvc9/AcpiComponents.sln
  56 
  57 The Windows versions of GNU Flex/Bison must be installed, and they must
  58 be installed in a directory that contains no embedded spaces in the
  59 pathname. They cannot be installed in the default "c:\Program Files"
  60 directory. This is a bug in Bison. The default Windows project file for
  61 iASL assumes that these tools are installed at this location:
  62 
  63     c:\GnuWin32
  64 
  65 Once the tools are installed, ensure that this path is added to the
  66 default system $Path environment variable:
  67 
  68     c:\GnuWin32\bin
  69 
  70 Goto: ControlPanel/System/AdvancedSystemSettings/EnvironmentVariables
  71 
  72 Important: Now Windows must be rebooted to make the system aware of
  73 the updated $Path. Otherwise, Bison will not be able to find the M4
  74 interpreter library and will fail.
  75 
  76 iASL has been generated with these versions of Flex/Bison for Windows:
  77 
  78     Flex for Windows:  V2.5.4a
  79     Bison for Windows: V2.4.1
  80 
  81 Flex is available at:  http://gnuwin32.sourceforge.net/packages/flex.htm
  82 Bison is available at: http://gnuwin32.sourceforge.net/packages/bison.htm
  83 
  84 
  85 
  86 2) Integration as a custom tool for Visual Studio
  87 -------------------------------------------------
  88 
  89 This procedure adds the iASL compiler as a custom tool that can be used
  90 to compile ASL source files. The output is sent to the VC output 
  91 window.
  92 
  93 a) Select Tools->Customize.
  94 
  95 b) Select the "Tools" tab.
  96 
  97 c) Scroll down to the bottom of the "Menu Contents" window. There you
  98    will see an empty rectangle. Click in the rectangle to enter a 
  99    name for this tool.
 100 
 101 d) Type "iASL Compiler" in the box and hit enter. You can now edit
 102    the other fields for this new custom tool.
 103 
 104 e) Enter the following into the fields:
 105 
 106    Command:             C:\Acpi\iasl.exe
 107    Arguments:           -vi "$(FilePath)"
 108    Initial Directory    "$(FileDir)"
 109    Use Output Window    <Check this option>
 110 
 111    "Command" must be the path to wherever you copied the compiler.
 112    "-vi" instructs the compiler to produce messages appropriate for VC.
 113    Quotes around FilePath and FileDir enable spaces in filenames.
 114 
 115 f) Select "Close".
 116 
 117 These steps will add the compiler to the tools menu as a custom tool.
 118 By enabling "Use Output Window", you can click on error messages in
 119 the output window and the source file and source line will be
 120 automatically displayed by VC. Also, you can use F4 to step through
 121 the messages and the corresponding source line(s).
 122 
 123 
 124 
 125 3) Integrating iASL into a Visual Studio ASL project build
 126 ----------------------------------------------------------
 127 
 128 This procedure creates a project that compiles ASL files to AML.
 129 
 130 a) Create a new, empty project and add your .ASL files to the project
 131 
 132 b) For all ASL files in the project, specify a custom build (under
 133 Project/Settings/CustomBuild with the following settings (or similar):
 134 
 135 Commands:
 136     c:\acpi\libraries\iasl.exe -vs -vi "$(InputPath)"
 137 
 138 Output:
 139     $(InputDir)\$(InputPath).aml