1/*
2 * Miscellaneous instructions for building and using the iASL compiler.
3 */
4Last update 9 December 2013.
5
6
71) Generating iASL from source
8------------------------------
9
10Generation 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
17There are three major ACPICA source code components that are required to
18generate the compiler (Basically, the entire ACPICA source tree should
19be 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
291a) Notes for Linux/Unix generation
30-----------------------------------
31
32iASL has been generated with these versions of Flex/Bison:
33
34    flex:  Version 2.5.32
35    bison: Version 2.6.2
36
37Other required packages:
38
39    make
40    gcc C compiler
41    m4 (macro processor required by bison)
42
43On 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
501b) Notes for Windows generation
51--------------------------------
52
53On Windows, the Visual Studio 2008 project file appears in this directory:
54
55    generate/msvc9/AcpiComponents.sln
56
57The Windows versions of GNU Flex/Bison must be installed, and they must
58be installed in a directory that contains no embedded spaces in the
59pathname. They cannot be installed in the default "c:\Program Files"
60directory. This is a bug in Bison. The default Windows project file for
61iASL assumes that these tools are installed at this location:
62
63    c:\GnuWin32
64
65Once the tools are installed, ensure that this path is added to the
66default system $Path environment variable:
67
68    c:\GnuWin32\bin
69
70Goto: ControlPanel/System/AdvancedSystemSettings/EnvironmentVariables
71
72Important: Now Windows must be rebooted to make the system aware of
73the updated $Path. Otherwise, Bison will not be able to find the M4
74interpreter library and will fail.
75
76iASL 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
81Flex is available at:  http://gnuwin32.sourceforge.net/packages/flex.htm
82Bison is available at: http://gnuwin32.sourceforge.net/packages/bison.htm
83
84
85
862) Integration as a custom tool for Visual Studio
87-------------------------------------------------
88
89This procedure adds the iASL compiler as a custom tool that can be used
90to compile ASL source files. The output is sent to the VC output
91window.
92
93a) Select Tools->Customize.
94
95b) Select the "Tools" tab.
96
97c) 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
101d) Type "iASL Compiler" in the box and hit enter. You can now edit
102   the other fields for this new custom tool.
103
104e) 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
115f) Select "Close".
116
117These steps will add the compiler to the tools menu as a custom tool.
118By enabling "Use Output Window", you can click on error messages in
119the output window and the source file and source line will be
120automatically displayed by VC. Also, you can use F4 to step through
121the messages and the corresponding source line(s).
122
123
124
1253) Integrating iASL into a Visual Studio ASL project build
126----------------------------------------------------------
127
128This procedure creates a project that compiles ASL files to AML.
129
130a) Create a new, empty project and add your .ASL files to the project
131
132b) For all ASL files in the project, specify a custom build (under
133Project/Settings/CustomBuild with the following settings (or similar):
134
135Commands:
136    c:\acpi\libraries\iasl.exe -vs -vi "$(InputPath)"
137
138Output:
139    $(InputDir)\$(InputPath).aml
140