[SR-13969] [docs] Describe how to quickly compile a minimal multi-module project

Previous ID	SR-13969
Radar	rdar://problem/72372588
Original Reporter	@typesanitizer
Type	Task

Votes	0
Component/s	Compiler
Labels	Task, StarterBug, StarterDocs
Assignee	None
Priority	Medium

md5: d39a4d68ef91ab7e6afa2ea6663b1ccb

Issue Description:

While creating minimal reproducers for issues, occasionally it is helpful to "hand-compile" a multi-module project quickly (say via a small shell script) without setting up an Xcode project or a Swift package. I don't think this is documented anywhere. Here are the main steps:

1. First compile the dependency module with mymodule.swift -emit-library -o /path/to/mymodule.dylib -emit-module-path /path/to/swiftmoduledir/.
2. Compile the executable with swiftc mymainmodule.swift -emit-object -o /path/to/mymainmodule.o -I /path/to/swiftmoduledir/
3. Link with swiftc /path/to/mymainmodule.o /path/to/mymodule.dylib -emit-executable -o /path/to/myexe
4. Run the executable normally, or optionally with the new runtime env DYLD_LIBRARY_PATH=/path/to/libswiftCore.dylib /path/to/myexe.

On Linux, the file suffixes would be different (do we support dynamic linking on Linux?), and I imagine replacing DYLD_LIBRARY_PATH with LD_LIBRARY_PATH should just work.

You can also import a module directory (i.e. containing a module.modulemap) with -I, or directly import a header -import-objc-header.

We should probably document some examples of invoking swiftc in the help page (right now, it has no examples ❗), and this could be the final example (and the most complicated one). the DYLD_LIBRARY_PATH bit is for development, so it's not super clear where we should write that down, but it's not necessarily obvious to a contributor that the locally built compiler compiler links in the OS runtime by default and not the locally built one.

One potential idea is to have simple example in --help, which would a subset of a new document under the docs/ directory. We can link the document from the --help page, so someone can follow it in case they want more complicated examples. The DYLD_LIBRARY_PATH "trick" can go into the doc without going into the --help information. If we create this new doc, we should also link it from docs/DebuggingTheCompiler.md.