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.