mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-10-18 18:42:46 +02:00
1aeeff713a
Users are exepcted to pass all .res files to the linker, which then merges all the resource in all .res files into a tree structure and then converts the final tree structure to a .obj file with .rsrc$01 and .rsrc$02 sections and then links that. If the user instead passes several .obj files containing such resources, the correct thing to do would be to have custom code to merge the trees in the resource sections instead of doing normal section merging -- but link.exe rejects if multiple resource obj files are passed in with LNK4078, so let lld-link do that too instead of silently writing broken .rsrc sections in that case. The only real way to run into this is if users manually convert .res files to .obj files by running cvtres and then handing the resulting .obj files to lld-link instead, which in practice likely never happens. (lld-link is slightly stricter than link.exe now: If link.exe is passed one .obj file created by cvtres, and a .res file, for some reason it just emits a warning instead of an error and outputs strange looking data. lld-link now errors out on mixed input like this.) One way users could accidentally run into this is the following scenario: If a .res file is passed to lib.exe, then lib.exe calls cvtres.exe on the .res file before putting it in the output .lib. (llvm-lib currently doesn't do this.) link.exe's /wholearchive seems to only add obj files referenced from the static library index, but lld-link current really adds all files in the archive. So if lld-link /wholearchive is used with .lib files produced by lib.exe and .res files were among the files handed to lib.exe, we previously silently produced invalid output, but now we error out. link.exe's /wholearchive semantics on the other hand mean that it wouldn't load the resource object files from the .lib file at all. Since this scenario is probably still an unlikely corner case, the difference in behavior here seems fine -- and lld-link might have to change to use link.exe's /wholearchive semantics in the future anyways. Vaguely related to PR42180. Differential Revision: https://reviews.llvm.org/D63109 llvm-svn: 363078 |
||
---|---|---|
.. | ||
build | ||
secondary | ||
.gitignore | ||
.gn | ||
get.py | ||
gn.py | ||
README.rst | ||
TODO.txt |
===================== Building LLVM with GN ===================== .. contents:: :local: .. _Introduction: Introduction ============ *Warning* The GN build is experimental and best-effort. It might not work, and if you use it you're expected to feel comfortable to unbreak it if necessary. LLVM's official build system is CMake, if in doubt use that. If you add files, you're expected to update the CMake build but you don't need to update GN build files. Reviewers should not ask authors to update GN build files. Keeping the GN build files up-to-date is on the people who use the GN build. `GN <https://gn.googlesource.com/gn/>`_ is a metabuild system. It always creates ninja files, but it can create some IDE projects (MSVC, Xcode, ...) which then shell out to ninja for the actual build. The main motivation behind the GN build is that some people find it more convenient for day-to-day hacking on LLVM than CMake. Distribution, building just parts of LLVM, and embedding the LLVM GN build from other builds are non-goals for the GN build. This is a `good overview of GN <https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit#slide=id.g119d702868_0_12>`_. .. _Quick start: Quick start =========== GN only works in the monorepo layout. #. ``git clone https://github.com/llvm/llvm-project.git; cd llvm-project`` if you don't have a monorepo checkout yet. #. ``llvm/utils/gn/get.py`` to download a prebuilt gn binary if you're on a 64-bit X86 system running Linux, macOS, or Windows. `Build gn yourself <https://gn.googlesource.com/gn/#getting-started>`_ if you're on a different platform or don't want to trust prebuilt binaries. #. ``llvm/utils/gn/gn.py gen out/gn`` to run GN and create build files. ``out/gn`` is the build directory, it can have any name, and you can have as many as you want, each with different build settings. (The ``gn.py`` script adds ``--dotfile=llvm/utils/gn/.gn --root=.`` and just runs regular ``gn``; you can manually pass these parameters and not use the wrapper if you prefer.) #. ``ninja -C out/gn check-lld`` to build all prerequisites for and run the LLD tests. By default, you get a release build with assertions enabled that targets the host arch. You can set build options by editing ``out/gn/args.gn``, for example putting ``is_debug = true`` in there gives you a debug build. Run ``llvm/utils/gn/gn.py args --list out/gn`` to see a list of all possible options. After touching ``out/gn/args.gn`` just run ninja: it will re-invoke gn before starting the build. GN has extensive built-in help; try e.g. ``llvm/utils/gn/gn.py help gen`` to see the help for the ``gen`` command. The full GN reference is also `available online <https://gn.googlesource.com/gn/+/master/docs/reference.md>`_. GN has an autoformatter: ``git ls-files '*.gn' '*.gni' | xargs llvm/utils/gn/gn.py format`` after making GN build changes is your friend. To not put ``BUILD.gn`` files into the main tree, they are all below ``utils/gn/secondary``. For example, the build file for ``llvm/lib/Support`` is in ``utils/gn/secondary/llvm/lib/Support``. .. _Syncing GN files from CMake files: Syncing GN files from CMake files ================================= Sometimes after pulling in the latest changes, the GN build doesn't work. Most of the time this is due to someone adding a file to CMakeLists.txt file. Run ``llvm/utils/gn/build/sync_source_lists_from_cmake.py`` to print a report of which files need to be added to or removed from ``BUILD.gn`` files to match the corresponding ``CMakeLists.txt``. You have to manually read the output of the script and implement its suggestions. If new ``CMakeLists.txt`` files have been added, you have to manually create a new corresponding ``BUILD.gn`` file below ``llvm/utils/gn/secondary/``. If the dependencies in a ``CMakeLists.txt`` file have been changed, you have to manually analyze and fix. .. _Philosophy: Philosophy ========== GN believes in using GN arguments to configure the build explicitly, instead of implicitly figuring out what to do based on what's available on the current system. configure is used for three classes of feature checks: - compiler checks. In GN, these could use exec_script to identify the host compiler at GN time. For now the build has explicit toggles for compiler features. (Maybe there could be a script that writes args.gn based on the host compiler). It's possible we'll use exec_script() for this going forward, but we'd have one exec_script call to identify compiler id and version, and then base GN arg default values of compiler id and version instead of doing one exec_script per feature check. (In theory, the config approach means a new os / compiler just needs to tweak the checks and not the code, but in practice a) new os's / compilers are rare b) they will require code changes anyhow, so the configure tradeoff seems not worth it.) - library checks. For e.g. like zlib, GN thinks it's better to say "we require zlib, else we error at build time" than silently omitting features. People who really don't want to install zlib can explicitly set the GN arg to turn off zlib. - header checks (does system header X exist). These are generally not needed (just keying this off the host OS works fine), but if they should become necessary in the future, they should be done at build time and the few targets that need to know if header X exists then depend on that build-time check while everything else can build parallel with it. - LLVM-specific build toggles (assertions on/off, debug on/off, targets to build, ...). These map cleanly to GN args (which then get copied into config.h in a build step). For the last two points, it would be nice if LLVM didn't have a single ``config.h`` header, but one header per toggle. That way, when e.g. ``llvm_enable_terminfo`` is toggled, only the 3 files caring about that setting would need to be rebuilt, instead of everything including ``config.h``. GN doesn't believe in users setting arbitrary cflags from an environment variable, it wants the build to be controlled by .gn files.