1//===- llvm-link.cpp - Low-level LLVM linker ------------------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This utility may be invoked in the following manner:
10// llvm-link a.bc b.bc c.bc -o x.bc
11//
12//===----------------------------------------------------------------------===//
13
14#include "llvm/ADT/STLExtras.h"
15#include "llvm/BinaryFormat/Magic.h"
16#include "llvm/Bitcode/BitcodeReader.h"
17#include "llvm/Bitcode/BitcodeWriter.h"
18#include "llvm/IR/AutoUpgrade.h"
19#include "llvm/IR/DiagnosticInfo.h"
20#include "llvm/IR/DiagnosticPrinter.h"
21#include "llvm/IR/LLVMContext.h"
22#include "llvm/IR/Module.h"
23#include "llvm/IR/ModuleSummaryIndex.h"
24#include "llvm/IR/Verifier.h"
25#include "llvm/IRReader/IRReader.h"
26#include "llvm/Linker/Linker.h"
27#include "llvm/Object/Archive.h"
28#include "llvm/Support/CommandLine.h"
29#include "llvm/Support/FileSystem.h"
30#include "llvm/Support/InitLLVM.h"
31#include "llvm/Support/Path.h"
32#include "llvm/Support/SourceMgr.h"
33#include "llvm/Support/SystemUtils.h"
34#include "llvm/Support/ToolOutputFile.h"
35#include "llvm/Support/WithColor.h"
36#include "llvm/Transforms/IPO/FunctionImport.h"
37#include "llvm/Transforms/IPO/Internalize.h"
38#include "llvm/Transforms/Utils/FunctionImportUtils.h"
39
40#include <memory>
41#include <utility>
42using namespace llvm;
43
44static cl::OptionCategory LinkCategory("Link Options");
45
46static cl::list<std::string> InputFilenames(cl::Positional, cl::OneOrMore,
47 cl::desc("<input bitcode files>"),
48 cl::cat(LinkCategory));
49
50static cl::list<std::string> OverridingInputs(
51 "override", cl::value_desc("filename"),
52 cl::desc(
53 "input bitcode file which can override previously defined symbol(s)"),
54 cl::cat(LinkCategory));
55
56// Option to simulate function importing for testing. This enables using
57// llvm-link to simulate ThinLTO backend processes.
58static cl::list<std::string> Imports(
59 "import", cl::value_desc("function:filename"),
60 cl::desc("Pair of function name and filename, where function should be "
61 "imported from bitcode in filename"),
62 cl::cat(LinkCategory));
63
64// Option to support testing of function importing. The module summary
65// must be specified in the case were we request imports via the -import
66// option, as well as when compiling any module with functions that may be
67// exported (imported by a different llvm-link -import invocation), to ensure
68// consistent promotion and renaming of locals.
69static cl::opt<std::string>
70 SummaryIndex("summary-index", cl::desc("Module summary index filename"),
71 cl::init(Val: ""), cl::value_desc("filename"),
72 cl::cat(LinkCategory));
73
74static cl::opt<std::string>
75 OutputFilename("o", cl::desc("Override output filename"), cl::init(Val: "-"),
76 cl::value_desc("filename"), cl::cat(LinkCategory));
77
78static cl::opt<bool> Internalize("internalize",
79 cl::desc("Internalize linked symbols"),
80 cl::cat(LinkCategory));
81
82static cl::opt<bool>
83 DisableDITypeMap("disable-debug-info-type-map",
84 cl::desc("Don't use a uniquing type map for debug info"),
85 cl::cat(LinkCategory));
86
87static cl::opt<bool> OnlyNeeded("only-needed",
88 cl::desc("Link only needed symbols"),
89 cl::cat(LinkCategory));
90
91static cl::opt<bool> Force("f", cl::desc("Enable binary output on terminals"),
92 cl::cat(LinkCategory));
93
94static cl::opt<bool> DisableLazyLoad("disable-lazy-loading",
95 cl::desc("Disable lazy module loading"),
96 cl::cat(LinkCategory));
97
98static cl::opt<bool> OutputAssembly("S",
99 cl::desc("Write output as LLVM assembly"),
100 cl::Hidden, cl::cat(LinkCategory));
101
102static cl::opt<bool> Verbose("v",
103 cl::desc("Print information about actions taken"),
104 cl::cat(LinkCategory));
105
106static cl::opt<bool> DumpAsm("d", cl::desc("Print assembly as linked"),
107 cl::Hidden, cl::cat(LinkCategory));
108
109static cl::opt<bool> SuppressWarnings("suppress-warnings",
110 cl::desc("Suppress all linking warnings"),
111 cl::init(Val: false), cl::cat(LinkCategory));
112
113static cl::opt<bool> PreserveBitcodeUseListOrder(
114 "preserve-bc-uselistorder",
115 cl::desc("Preserve use-list order when writing LLVM bitcode."),
116 cl::init(Val: true), cl::Hidden, cl::cat(LinkCategory));
117
118static cl::opt<bool> PreserveAssemblyUseListOrder(
119 "preserve-ll-uselistorder",
120 cl::desc("Preserve use-list order when writing LLVM assembly."),
121 cl::init(Val: false), cl::Hidden, cl::cat(LinkCategory));
122
123static cl::opt<bool> NoVerify("disable-verify",
124 cl::desc("Do not run the verifier"), cl::Hidden,
125 cl::cat(LinkCategory));
126
127static cl::opt<bool> IgnoreNonBitcode(
128 "ignore-non-bitcode",
129 cl::desc("Do not report an error for non-bitcode files in archives"),
130 cl::Hidden);
131
132static cl::opt<bool> TryUseNewDbgInfoFormat(
133 "try-experimental-debuginfo-iterators",
134 cl::desc("Enable debuginfo iterator positions, if they're built in"),
135 cl::init(Val: false));
136
137extern cl::opt<bool> UseNewDbgInfoFormat;
138
139static ExitOnError ExitOnErr;
140
141// Read the specified bitcode file in and return it. This routine searches the
142// link path for the specified file to try to find it...
143//
144static std::unique_ptr<Module> loadFile(const char *argv0,
145 std::unique_ptr<MemoryBuffer> Buffer,
146 LLVMContext &Context,
147 bool MaterializeMetadata = true) {
148 SMDiagnostic Err;
149 if (Verbose)
150 errs() << "Loading '" << Buffer->getBufferIdentifier() << "'\n";
151 std::unique_ptr<Module> Result;
152 if (DisableLazyLoad)
153 Result = parseIR(Buffer: *Buffer, Err, Context);
154 else
155 Result =
156 getLazyIRModule(Buffer: std::move(Buffer), Err, Context, ShouldLazyLoadMetadata: !MaterializeMetadata);
157
158 if (!Result) {
159 Err.print(ProgName: argv0, S&: errs());
160 return nullptr;
161 }
162
163 if (MaterializeMetadata) {
164 ExitOnErr(Result->materializeMetadata());
165 UpgradeDebugInfo(M&: *Result);
166 }
167
168 return Result;
169}
170
171static std::unique_ptr<Module> loadArFile(const char *Argv0,
172 std::unique_ptr<MemoryBuffer> Buffer,
173 LLVMContext &Context) {
174 std::unique_ptr<Module> Result(new Module("ArchiveModule", Context));
175 StringRef ArchiveName = Buffer->getBufferIdentifier();
176 if (Verbose)
177 errs() << "Reading library archive file '" << ArchiveName
178 << "' to memory\n";
179 Expected<std::unique_ptr<object::Archive>> ArchiveOrError =
180 object::Archive::create(Source: Buffer->getMemBufferRef());
181 if (!ArchiveOrError)
182 ExitOnErr(ArchiveOrError.takeError());
183
184 std::unique_ptr<object::Archive> Archive = std::move(ArchiveOrError.get());
185
186 Linker L(*Result);
187 Error Err = Error::success();
188 for (const object::Archive::Child &C : Archive->children(Err)) {
189 Expected<StringRef> Ename = C.getName();
190 if (Error E = Ename.takeError()) {
191 errs() << Argv0 << ": ";
192 WithColor::error() << " failed to read name of archive member"
193 << ArchiveName << "'\n";
194 return nullptr;
195 }
196 std::string ChildName = Ename.get().str();
197 if (Verbose)
198 errs() << "Parsing member '" << ChildName
199 << "' of archive library to module.\n";
200 SMDiagnostic ParseErr;
201 Expected<MemoryBufferRef> MemBuf = C.getMemoryBufferRef();
202 if (Error E = MemBuf.takeError()) {
203 errs() << Argv0 << ": ";
204 WithColor::error() << " loading memory for member '" << ChildName
205 << "' of archive library failed'" << ArchiveName
206 << "'\n";
207 return nullptr;
208 };
209
210 if (!isBitcode(BufPtr: reinterpret_cast<const unsigned char *>(
211 MemBuf.get().getBufferStart()),
212 BufEnd: reinterpret_cast<const unsigned char *>(
213 MemBuf.get().getBufferEnd()))) {
214 if (IgnoreNonBitcode)
215 continue;
216 errs() << Argv0 << ": ";
217 WithColor::error() << " member of archive is not a bitcode file: '"
218 << ChildName << "'\n";
219 return nullptr;
220 }
221
222 std::unique_ptr<Module> M;
223 if (DisableLazyLoad)
224 M = parseIR(Buffer: MemBuf.get(), Err&: ParseErr, Context);
225 else
226 M = getLazyIRModule(Buffer: MemoryBuffer::getMemBuffer(Ref: MemBuf.get(), RequiresNullTerminator: false),
227 Err&: ParseErr, Context);
228
229 if (!M.get()) {
230 errs() << Argv0 << ": ";
231 WithColor::error() << " parsing member '" << ChildName
232 << "' of archive library failed'" << ArchiveName
233 << "'\n";
234 return nullptr;
235 }
236 if (Verbose)
237 errs() << "Linking member '" << ChildName << "' of archive library.\n";
238 if (L.linkInModule(Src: std::move(M)))
239 return nullptr;
240 } // end for each child
241 ExitOnErr(std::move(Err));
242 return Result;
243}
244
245namespace {
246
247/// Helper to load on demand a Module from file and cache it for subsequent
248/// queries during function importing.
249class ModuleLazyLoaderCache {
250 /// Cache of lazily loaded module for import.
251 StringMap<std::unique_ptr<Module>> ModuleMap;
252
253 /// Retrieve a Module from the cache or lazily load it on demand.
254 std::function<std::unique_ptr<Module>(const char *argv0,
255 const std::string &FileName)>
256 createLazyModule;
257
258public:
259 /// Create the loader, Module will be initialized in \p Context.
260 ModuleLazyLoaderCache(std::function<std::unique_ptr<Module>(
261 const char *argv0, const std::string &FileName)>
262 createLazyModule)
263 : createLazyModule(std::move(createLazyModule)) {}
264
265 /// Retrieve a Module from the cache or lazily load it on demand.
266 Module &operator()(const char *argv0, const std::string &FileName);
267
268 std::unique_ptr<Module> takeModule(const std::string &FileName) {
269 auto I = ModuleMap.find(Key: FileName);
270 assert(I != ModuleMap.end());
271 std::unique_ptr<Module> Ret = std::move(I->second);
272 ModuleMap.erase(I);
273 return Ret;
274 }
275};
276
277// Get a Module for \p FileName from the cache, or load it lazily.
278Module &ModuleLazyLoaderCache::operator()(const char *argv0,
279 const std::string &Identifier) {
280 auto &Module = ModuleMap[Identifier];
281 if (!Module) {
282 Module = createLazyModule(argv0, Identifier);
283 assert(Module && "Failed to create lazy module!");
284 }
285 return *Module;
286}
287} // anonymous namespace
288
289namespace {
290struct LLVMLinkDiagnosticHandler : public DiagnosticHandler {
291 bool handleDiagnostics(const DiagnosticInfo &DI) override {
292 unsigned Severity = DI.getSeverity();
293 switch (Severity) {
294 case DS_Error:
295 WithColor::error();
296 break;
297 case DS_Warning:
298 if (SuppressWarnings)
299 return true;
300 WithColor::warning();
301 break;
302 case DS_Remark:
303 case DS_Note:
304 llvm_unreachable("Only expecting warnings and errors");
305 }
306
307 DiagnosticPrinterRawOStream DP(errs());
308 DI.print(DP);
309 errs() << '\n';
310 return true;
311 }
312};
313} // namespace
314
315/// Import any functions requested via the -import option.
316static bool importFunctions(const char *argv0, Module &DestModule) {
317 if (SummaryIndex.empty())
318 return true;
319 std::unique_ptr<ModuleSummaryIndex> Index =
320 ExitOnErr(llvm::getModuleSummaryIndexForFile(Path: SummaryIndex));
321
322 // Map of Module -> List of globals to import from the Module
323 FunctionImporter::ImportMapTy ImportList;
324
325 auto ModuleLoader = [&DestModule](const char *argv0,
326 const std::string &Identifier) {
327 std::unique_ptr<MemoryBuffer> Buffer =
328 ExitOnErr(errorOrToExpected(EO: MemoryBuffer::getFileOrSTDIN(Filename: Identifier)));
329 return loadFile(argv0, Buffer: std::move(Buffer), Context&: DestModule.getContext(), MaterializeMetadata: false);
330 };
331
332 ModuleLazyLoaderCache ModuleLoaderCache(ModuleLoader);
333 // Owns the filename strings used to key into the ImportList. Normally this is
334 // constructed from the index and the strings are owned by the index, however,
335 // since we are synthesizing this data structure from options we need a cache
336 // to own those strings.
337 StringSet<> FileNameStringCache;
338 for (const auto &Import : Imports) {
339 // Identify the requested function and its bitcode source file.
340 size_t Idx = Import.find(c: ':');
341 if (Idx == std::string::npos) {
342 errs() << "Import parameter bad format: " << Import << "\n";
343 return false;
344 }
345 std::string FunctionName = Import.substr(pos: 0, n: Idx);
346 std::string FileName = Import.substr(pos: Idx + 1, n: std::string::npos);
347
348 // Load the specified source module.
349 auto &SrcModule = ModuleLoaderCache(argv0, FileName);
350
351 if (!NoVerify && verifyModule(M: SrcModule, OS: &errs())) {
352 errs() << argv0 << ": " << FileName;
353 WithColor::error() << "input module is broken!\n";
354 return false;
355 }
356
357 Function *F = SrcModule.getFunction(Name: FunctionName);
358 if (!F) {
359 errs() << "Ignoring import request for non-existent function "
360 << FunctionName << " from " << FileName << "\n";
361 continue;
362 }
363 // We cannot import weak_any functions without possibly affecting the
364 // order they are seen and selected by the linker, changing program
365 // semantics.
366 if (F->hasWeakAnyLinkage()) {
367 errs() << "Ignoring import request for weak-any function " << FunctionName
368 << " from " << FileName << "\n";
369 continue;
370 }
371
372 if (Verbose)
373 errs() << "Importing " << FunctionName << " from " << FileName << "\n";
374
375 auto &Entry =
376 ImportList[FileNameStringCache.insert(key: FileName).first->getKey()];
377 Entry.insert(x: F->getGUID());
378 }
379 auto CachedModuleLoader = [&](StringRef Identifier) {
380 return ModuleLoaderCache.takeModule(FileName: std::string(Identifier));
381 };
382 FunctionImporter Importer(*Index, CachedModuleLoader,
383 /*ClearDSOLocalOnDeclarations=*/false);
384 ExitOnErr(Importer.importFunctions(M&: DestModule, ImportList));
385
386 return true;
387}
388
389static bool linkFiles(const char *argv0, LLVMContext &Context, Linker &L,
390 const cl::list<std::string> &Files, unsigned Flags) {
391 // Filter out flags that don't apply to the first file we load.
392 unsigned ApplicableFlags = Flags & Linker::Flags::OverrideFromSrc;
393 // Similar to some flags, internalization doesn't apply to the first file.
394 bool InternalizeLinkedSymbols = false;
395 for (const auto &File : Files) {
396 std::unique_ptr<MemoryBuffer> Buffer =
397 ExitOnErr(errorOrToExpected(EO: MemoryBuffer::getFileOrSTDIN(Filename: File)));
398
399 std::unique_ptr<Module> M =
400 identify_magic(magic: Buffer->getBuffer()) == file_magic::archive
401 ? loadArFile(Argv0: argv0, Buffer: std::move(Buffer), Context)
402 : loadFile(argv0, Buffer: std::move(Buffer), Context);
403 if (!M.get()) {
404 errs() << argv0 << ": ";
405 WithColor::error() << " loading file '" << File << "'\n";
406 return false;
407 }
408
409 // Note that when ODR merging types cannot verify input files in here When
410 // doing that debug metadata in the src module might already be pointing to
411 // the destination.
412 if (DisableDITypeMap && !NoVerify && verifyModule(M: *M, OS: &errs())) {
413 errs() << argv0 << ": " << File << ": ";
414 WithColor::error() << "input module is broken!\n";
415 return false;
416 }
417
418 // If a module summary index is supplied, load it so linkInModule can treat
419 // local functions/variables as exported and promote if necessary.
420 if (!SummaryIndex.empty()) {
421 std::unique_ptr<ModuleSummaryIndex> Index =
422 ExitOnErr(llvm::getModuleSummaryIndexForFile(Path: SummaryIndex));
423
424 // Conservatively mark all internal values as promoted, since this tool
425 // does not do the ThinLink that would normally determine what values to
426 // promote.
427 for (auto &I : *Index) {
428 for (auto &S : I.second.SummaryList) {
429 if (GlobalValue::isLocalLinkage(Linkage: S->linkage()))
430 S->setLinkage(GlobalValue::ExternalLinkage);
431 }
432 }
433
434 // Promotion
435 if (renameModuleForThinLTO(M&: *M, Index: *Index,
436 /*ClearDSOLocalOnDeclarations=*/false))
437 return true;
438 }
439
440 if (Verbose)
441 errs() << "Linking in '" << File << "'\n";
442
443 bool Err = false;
444 if (InternalizeLinkedSymbols) {
445 Err = L.linkInModule(
446 Src: std::move(M), Flags: ApplicableFlags, InternalizeCallback: [](Module &M, const StringSet<> &GVS) {
447 internalizeModule(TheModule&: M, MustPreserveGV: [&GVS](const GlobalValue &GV) {
448 return !GV.hasName() || (GVS.count(Key: GV.getName()) == 0);
449 });
450 });
451 } else {
452 Err = L.linkInModule(Src: std::move(M), Flags: ApplicableFlags);
453 }
454
455 if (Err)
456 return false;
457
458 // Internalization applies to linking of subsequent files.
459 InternalizeLinkedSymbols = Internalize;
460
461 // All linker flags apply to linking of subsequent files.
462 ApplicableFlags = Flags;
463 }
464
465 return true;
466}
467
468int main(int argc, char **argv) {
469 InitLLVM X(argc, argv);
470 ExitOnErr.setBanner(std::string(argv[0]) + ": ");
471
472 cl::HideUnrelatedOptions(Categories: {&LinkCategory, &getColorCategory()});
473 cl::ParseCommandLineOptions(argc, argv, Overview: "llvm linker\n");
474
475 // RemoveDIs debug-info transition: tests may request that we /try/ to use the
476 // new debug-info format.
477 if (TryUseNewDbgInfoFormat) {
478 // Turn the new debug-info format on.
479 UseNewDbgInfoFormat = true;
480 }
481
482 LLVMContext Context;
483 Context.setDiagnosticHandler(DH: std::make_unique<LLVMLinkDiagnosticHandler>(),
484 RespectFilters: true);
485
486 if (!DisableDITypeMap)
487 Context.enableDebugTypeODRUniquing();
488
489 auto Composite = std::make_unique<Module>(args: "llvm-link", args&: Context);
490 Linker L(*Composite);
491
492 unsigned Flags = Linker::Flags::None;
493 if (OnlyNeeded)
494 Flags |= Linker::Flags::LinkOnlyNeeded;
495
496 // First add all the regular input files
497 if (!linkFiles(argv0: argv[0], Context, L, Files: InputFilenames, Flags))
498 return 1;
499
500 // Next the -override ones.
501 if (!linkFiles(argv0: argv[0], Context, L, Files: OverridingInputs,
502 Flags: Flags | Linker::Flags::OverrideFromSrc))
503 return 1;
504
505 // Import any functions requested via -import
506 if (!importFunctions(argv0: argv[0], DestModule&: *Composite))
507 return 1;
508
509 if (DumpAsm)
510 errs() << "Here's the assembly:\n" << *Composite;
511
512 std::error_code EC;
513 ToolOutputFile Out(OutputFilename, EC,
514 OutputAssembly ? sys::fs::OF_TextWithCRLF
515 : sys::fs::OF_None);
516 if (EC) {
517 WithColor::error() << EC.message() << '\n';
518 return 1;
519 }
520
521 if (!NoVerify && verifyModule(M: *Composite, OS: &errs())) {
522 errs() << argv[0] << ": ";
523 WithColor::error() << "linked module is broken!\n";
524 return 1;
525 }
526
527 if (Verbose)
528 errs() << "Writing bitcode...\n";
529 if (OutputAssembly) {
530 Composite->print(OS&: Out.os(), AAW: nullptr, ShouldPreserveUseListOrder: PreserveAssemblyUseListOrder);
531 } else if (Force || !CheckBitcodeOutputToConsole(stream_to_check&: Out.os()))
532 WriteBitcodeToFile(M: *Composite, Out&: Out.os(), ShouldPreserveUseListOrder: PreserveBitcodeUseListOrder);
533
534 // Declare success.
535 Out.keep();
536
537 return 0;
538}
539

source code of llvm/tools/llvm-link/llvm-link.cpp