mirror of
https://github.com/tianocore/edk2
synced 2026-08-27 00:23:19 -04:00
a59064933f
When Trim processes an ASL file (`--asl-file`), it textually inlines
the body of every `Include()`'d file directly into the constructed
preprocessor input, once per include site.
Its has duplicate protection in the form of a circular-include stack
(`gIncludedAslFile`), that prevents A->B->A cycles. But, as far as
the script is concerned, each `Include()` is a unique include site.
Various combinations of includes and file types are possible and
handled slightly differently.
Starting with file types as defined in
BaseTools\Conf\build_rule.template:
- `.aslc`, `.act` files fall under `Acpi-Table-Code-File` and are
compiled, linked, and processed by genfw.
- `.asl`, `.Asl`, and `.ASL` files fall in `Acpi-Source-Language-File`
and are processed by Trim:
1. `Trim --asl-file` to produce a single combined .i file with
includes inlined.
2. `ASLPP` (ASL preprocessor, a C preprocessor) on the output of
Trim to produce a .iii file with all macros expanded and
conditional branches resolved. AutoGen.h is also included and
processed here to resolve fixed PCD values if needed.
3. `Trim --source-code` which takes the pre-processed .iii file and
produces a .iiii file with content like linemarkers cleaned up.
4. The ACPI compiler compiles the .iiii file to produce AML bytecode
in a .aml file.
Because the `.aslc`/`.act` files are directly passed to normal C
processing tools, they are not part of the Trim change made in this
commit and the remainder of this message focuses on the ACPI Source
Language File case.
ASL files can use either an ASL `Include()` directive or a C-style
`#include` directive. In addition, different file types may be
included such as a `.asl` file or a `.h` file.
`Trim` handles these cases differently:
- For ASL `Include()` directives, `Trim` inlines the content of the
included file directly into the output at the include site. This is
done for all included ASL files regardless of their extension. The
inlining is purely textual and does not attempt to resolve or
preserve any preprocessor directives such as `#pragma once` or
include guards.
- For C-style `#include` directives, `Trim` checks the file extension
of the included file. If the file is an ASL file (`.asl` or `.asi`),
`Trim` treats the file the same as the `Include()` case. Otherwise,
`Trim` passes the directive through verbatim to the output, allowing
the downstream C preprocessor (`ASLPP`) to handle it according to
normal C preprocessor rules.
This creates a situtation in which the resulting `.i` might include:
- Inlined file content (from a `.asl` or `.h` file) depending on the
include type and file extension.
- Verbatim `#include` directives for non-ASL files which will be
processed by the C preprocessor.
Focusing on the "inlined" case, historically `.h` files would have
traditional C include guards (`#ifndef`/`#define`, `#endif`). However,
files might also include `#pragma once` as a guard.
In that case, the inlined content of the `.i` file could contain
multiple `#pragma once` directives, one per include site. When the
C preprocessor (`ASLPP`) processes the `.i` file, it sees multiple
`#pragma once` directives in what it considers the main file, and
could emit a warning like the following from gcc:
warning: '#pragma once' in main file [-Wpragma-once-outside-header]
The remainder of this commit message describes the change made to
address this warning.
This change strips "#pragma once" lines on the ASL content path in
`DoInclude()` in `Trim.py` so the directive is removed before it
reaches the C preprocessor.
- "#include" directives for non-ASL files are still passed through
verbatim for the C preprocessor to resolve where the contents of
those .h files might contain "#pragma once" or traditional guards.
- Traditional include guards are untouched and continue to behave as
before where multiple include sites might inline the same content
in the .i file before reaching the C preprocessor.
The change:
In the case that a file is inlined with a `#pragma once` directive,
the directive is stripped from the inlined content which prevents the
warning.
This is considered acceptable because it only removes the
`#pragma once` directive from the inlined content for these specific
cases. So, the `.i` file might contain multiple inlined copies of the
same header content (like always in this inline case) but without the
`#pragma once` directives. Because actual C content was already not
processed or trimmed out (e.g. `typedef struct`) duplicate content is
not considered to be a problem (`#define` multiple times is not a
problem for the C preprocessor).
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
|
||
|---|---|---|
| .. | ||
| Bin | ||
| BinWrappers | ||
| Conf | ||
| Plugin | ||
| Scripts | ||
| Source | ||
| Tests | ||
| UserManuals | ||
| .gitignore | ||
| basetools_calling_path_env.yaml | ||
| basetools_path_env.yaml | ||
| BuildEnv | ||
| Edk2ToolsBuild.py | ||
| get_vsvars.bat | ||
| GNUmakefile | ||
| Makefile | ||
| ReadMe.rst | ||
| set_vsprefix_envs.bat | ||
| toolsetup.bat | ||
:: Note: New build instructions are available. It is recommended to start with the new instructions if learning how to build edk2 and/or BaseTools for the first time. This page is retained for reference. New instructions: `Build Instructions`_ .. _`Build Instructions`: https://github.com/tianocore/tianocore.github.io/wiki/Build-Instructions This directory contains the EDK II build tools and template files. Templates are located in the Conf directory, while the tools executables for Microsoft Windows Operating Systems are located in the Bin\\Win32 directory, other directory contains tools source. Build step to generate the binary tools --------------------------------------- Windows/Visual Studio Notes =========================== To build the BaseTools, you should run the standard vsvars32.bat script from your preferred Visual Studio installation or you can run get_vsvars.bat to use latest automatically detected version. In addition to this, you should set the following environment variables:: * EDK_TOOLS_PATH - Path to the BaseTools sub directory under the edk2 tree * BASE_TOOLS_PATH - The directory where the BaseTools source is located. (It is the same directory where this README.rst is located.) After this, you can run the toolsetup.bat file, which is in the same directory as this file. It should setup the remainder of the environment, and build the tools if necessary. Unix-like operating systems =========================== To build on Unix-like operating systems, you only need to type ``make`` in the base directory of the project. Ubuntu Notes ============ On Ubuntu, the following command should install all the necessary build packages to build all the C BaseTools:: sudo apt install build-essential uuid-dev