[docs] Add an external description of the swiftc driver. #4992
Conversation
|
@modocache, @abertelrud, @rballard, @ddunbar, @gribozavr, anyone else: thoughts / suggestions? |
| be part of the same module. Doing anything else is unsupported. | ||
|
|
||
| - The _driver_ is the program that's run when you invoke `swift` or `swiftc` | ||
| directly. This doesn't actually compile anything itself; instead it invokes |
There was a problem hiding this comment.
I found "directly" vague here. I understand the driver to be the program that's run when you invoke these executables without using the -frontend flag. The driver generates a series of commands that, for the most part, simply invoke swift -frontend.
"Directly" to me is unintuitive because when I invoke swift MyFile.swift, my understanding is that that's a pretty "direct" invocation. An "indirect" invocation would be when I invoke xcodebuild or something.
So, perhaps change the wording here a bit?
| mode, executes it via a JIT). | ||
|
|
||
| The frontend is an implementation detail. No aspects of its command-line | ||
| interface are considered stable. Even its existence isn't guaranteed. |
|
|
||
| (It *would* be nice to have a way to get reasonable default behavior by | ||
| pointing `-o` at a directory, or by adding an `-intermediate-directory` | ||
| argument or something. Patches welcome.) |
There was a problem hiding this comment.
Do these niceties come with Swift JIRA tasks? Linking to those would make it (a) easy for contributors to start that work, and (b) easy to understand when this blurb can be deleted from this doc.
| Threaded mode is controlled by the `-num-threads` command-line option rather | ||
| than `-j` used to control the number of jobs (simultaneous subprocesses spawned | ||
| by the driver). Why? Well, they're not quite setting the same thing...but it's | ||
| unclear whether that difference is buying us anything. |
There was a problem hiding this comment.
Could you elaborate? As a reader, I would have expected the next paragraph to go into detail on why you thought the difference didn't have any benefits. As is, on the other hand, I just have unanswered questions lingering in my brain.
Perhaps pare this down to just:
Threaded mode is controlled by the
-num-threadscommand-line option rather than-j, which is used to control the number of jobs (simultaneous subprocesses spawned by the driver).
There was a problem hiding this comment.
I actually can't remember the reasoning but I think I talked it through with @eeckstein at the time and it made sense. Erik, do you remember?
There was a problem hiding this comment.
The reason is that applying -num-threads changes the generated code (even with an argument of 1). In theory it should not be performance relevant, but still, the code is different.
One would assume that -j has no influence on the generated code.
| them they can be omitted. | ||
|
|
||
| The output file map accepts other entries, but they should not be considered | ||
| stable. Please stick to what's shown here. |
There was a problem hiding this comment.
I think we should document the "dependencies" key too, since you shouldn't be trying to do incremental compilation without also tracking the Clang module header deps.
There was a problem hiding this comment.
Oh, good point.
| "swift-dependencies": "/path/to/build/bar.swiftdeps", | ||
| "diagnostics": "/path/to/build/bar.dia", | ||
| }, | ||
| "": { |
There was a problem hiding this comment.
Maybe clarify this record doesn't map to anything?
| Whole-module builds actually have two modes: threaded and non-threaded. The | ||
| default is non-threaded, which produces a single object file for the entire | ||
| compilation unit (.o). If you're just producing object files, you can use the | ||
| usual `-o` option with `-c` to control where the single output goes. |
There was a problem hiding this comment.
We should probably document the location of this in the object file map mode is controlled by the "object" entry of the "master" (i.e. "" entry).
There was a problem hiding this comment.
Do we prefer that over -o/-c? In this guide, you shouldn't care about where intermediates go.
|
Looks great, and kudos for taking the time to write it up! |
jrose-apple
force-pushed
the
Driver.md
branch
from
21d95c2 to
fea0473
Compare
|
Addressed review feedback. @swift-ci Please smoke test |
| "diagnostics": "/path/to/build/foo.dia", | ||
| }, | ||
| "/path/to/src/bar.swift": { | ||
| "object": "/path/to/build/bar.o" |
There was a problem hiding this comment.
nitpick: missing comma.
Also, trailing comma ( e.g. ... .dia", }) are accepted?
There was a problem hiding this comment.
Oops, too used to YAML. Will fix.
Aimed at people writing build systems who won't be satisfied with "just use xcodebuild" or "just use SwiftPM", mostly because they'll go ahead doing what they're doing anyway and it'll be incorrect.
jrose-apple
force-pushed
the
Driver.md
branch
from
fea0473 to
e45bb49
Compare
|
@swift-ci Please smoke test |
|
@swift-ci Please smoke test Linux platform |
Aimed at people writing build systems who won't be satisfied with "just use xcodebuild" or "just use SwiftPM", mostly because they'll go ahead doing what they're doing anyway and it'll be incorrect.