Skip to content
← Back

src/syntax/process/select_entry_point.ghul

1
namespace Syntax.Process is
2
use Source.LOCATION
3
use Trees
4
5
use Logging.Logger
6
7
use Semantic.Symbols.Function
8
9
// Picks the assembly's entry point out of every candidate the project
10
// declares, before generate-il runs.
11
//
12
// Three kinds of declaration can name one, and they rank against each
13
// other rather than competing first-come:
14
//
15
// 1. an `@entry` (or `@IL.entrypoint`) pragma
16
// 2. a function named by `--entry`, or `entry` when that is not given
17
// 3. the entry synthesised from a file's top-level statements
18
//
19
// The highest rank any candidate reaches wins, and two candidates at
20
// that rank are the duplicate-entrypoint error - except at rank 3,
21
// where several files each carrying top-level statements is a project
22
// shape rather than a mistake: none of them is selected, each is told
23
// its statements will not run, and an executable build that ends up
24
// with no entry point at all reports that separately.
25
//
26
// Ranking matters most for rank 3. A synthesised entry is a file-private
27
// definition like any other, so a project may hold any number of them -
28
// an umbrella project globbing a directory of one-file examples, say -
29
// and naming the real entry point with `--entry` is what tells them
30
// apart. `--entry` also takes rank 3 out of the running entirely: a
31
// build that asks for an entry point by name does not want statements
32
// from some other file instead.
33
// A declaration of the entry-point name whose shape cannot be
34
// entered at, and which part of it says so.
35
class REJECTED_ENTRY_NAME(location: LOCATION, name: string, fault: string)
36
37
class SELECT_ENTRY_POINT: Visitor is
38
UNRUN_STATEMENTS: string static => "top-level-statements-not-run"
39
40
_PRAGMA_RANK: int static => 0
41
_NAMED_RANK: int static => 1
42
_TOP_LEVEL_RANK: int static => 2
43
44
_logger: Logger
45
_symbol_table: Semantic.SYMBOL_TABLE
46
_entry_point: Compiler.ENTRY_POINT
47
_build_flags: Compiler.GLOBAL_BUILD_FLAGS
48
49
_candidates: Collections.LIST[ENTRY_POINT_CANDIDATE]
50
_pending_entry_pragma: bool
51
52
// The function declaration the next synthesised `_entry` wrapper
53
// stands in for. The wrapper is appended after the original in its
54
// definition list, so the original is always walked first.
55
_wrapped_original: Definitions.FUNCTION?
56
57
// A declaration of the entry-point name that cannot be entered
58
// at, held until the choice is made: whether it is a fault at
59
// all depends on what else the build found.
60
_rejected_named: REJECTED_ENTRY_NAME?
61
62
// Whether a function the entry-point name selects was rejected
63
// for its shape. The program has said where it starts, so the
64
// statements of some other file are not taken in its place -
65
// starting somewhere the author did not name is as surprising as
66
// not starting at all, and the error at the function is the
67
// whole of what to say about it.
68
_entry_name_claimed: bool
69
70
// Whether the project carries top-level statements that no build
71
// will run. Read by the compiler so an executable build with no
72
// entry point can say which of the two shapes it is in.
73
left_top_level_statements_unrun: bool public
74
75
// Whether `--entry` named a function that no candidate matches -
76
// distinct from several top-level files leaving the choice open,
77
// since here the caller did name one and nothing answered to it.
78
// Read by the compiler for the same reason as the field above.
79
named_entry_point_not_found: bool public
80
81
init(
82
logger: Logger,
83
symbol_table: Semantic.SYMBOL_TABLE,
84
entry_point: Compiler.ENTRY_POINT,
85
build_flags: Compiler.GLOBAL_BUILD_FLAGS
86
) is
87
super.init()
88
89
_logger = logger
90
_symbol_table = symbol_table
91
_entry_point = entry_point
92
_build_flags = build_flags
93
_candidates = Collections.LIST[ENTRY_POINT_CANDIDATE]()
94
si
95
96
start() is
97
_candidates.clear()
98
_pending_entry_pragma = false
99
_entry_name_claimed = false
100
_rejected_named = null
101
left_top_level_statements_unrun = false
102
named_entry_point_not_found = false
103
si
104
105
apply(source_file: Compiler.SOURCE_FILE) is
106
_pending_entry_pragma = false
107
_wrapped_original = null
108
109
source_file.definition.walk(self)
110
si
111
112
pre(pragma: Definitions.PRAGMA) -> bool is
113
let name = pragma.pragma.name.to_string()
114
115
if name =~ "entry" \/ name =~ IL_PRAGMAS.ENTRYPOINT then
116
_pending_entry_pragma = true
117
fi
118
119
return false
120
si
121
122
pre(function: Definitions.FUNCTION) -> bool is
123
let is_pragma_marked = _pending_entry_pragma
124
125
_pending_entry_pragma = false
126
127
// Stands in for by a synthesised `_entry` wrapper: this
128
// function's own signature is never Main-compatible, so it
129
// is never itself a candidate. Remembered, so the wrapper's
130
// candidate can describe this declaration - the user wrote
131
// this one, and no diagnostic should name the wrapper.
132
if function.wrapped_by_synthesized_main then
133
_wrapped_original = function
134
return true
135
fi
136
137
let name = function.name
138
let is_named_entry =
139
(name? /\ name.name =~ _entry_point.name) \/
140
function.is_synthesized_main_wrapper
141
142
// Nothing inside a body can be a candidate - a lambda is never
143
// one, and a function cannot nest - so the walk stops at every
144
// function header rather than descending through every
145
// expression in the project. The three cheap tests come first
146
// so the vast majority of headers cost a string compare and
147
// never reach the symbol table.
148
if !function.is_top_level_entry /\ !is_pragma_marked /\ !is_named_entry then
149
return true
150
fi
151
152
let symbol = _function_for(function)
153
154
// Only the two kinds the runtime can enter at: a global
155
// function or a static method. An instance method named
156
// `entry` is an ordinary member.
157
if !symbol? \/ !(isa Semantic.Symbols.GLOBAL_FUNCTION(symbol) \/ isa Semantic.Symbols.STATIC_METHOD(symbol)) then
158
return true
159
fi
160
161
let declared_at = if name? then name.location else function.location fi
162
163
// A cell's entry, and the wrapper beside it, are run by whatever
164
// runs the session, never as the program's entry point.
165
if _build_flags.want_cells /\ (function.is_top_level_entry \/ function.wraps_top_level_entry) then
166
return true
167
fi
168
169
if function.is_top_level_entry then
170
_candidates.add(
171
ENTRY_POINT_CANDIDATE(
172
_TOP_LEVEL_RANK,
173
symbol,
174
_first_statement_location(function),
175
true,
176
symbol.name))
177
elif function.is_synthesized_main_wrapper then
178
// Emission enters the wrapper, but no diagnostic should
179
// name it: the candidate borrows the wrapped declaration's
180
// name and a location the user can jump to. A wrapper for a
181
// top-level entry carries the top-level rank - several files
182
// each holding statements stay the tolerated tie they are
183
// without wrappers, and `--entry` still takes them all out
184
// of the running.
185
let original = _wrapped_original
186
187
let wrapped_name =
188
if original? /\ original.name? then
189
original.name.name
190
else
191
symbol.name
192
fi
193
194
let wrapped_location =
195
if original? /\ original.is_top_level_entry then
196
_first_statement_location(original)
197
elif original? /\ original.name? then
198
original.name.location
199
else
200
declared_at
201
fi
202
203
let rank = if function.wraps_top_level_entry then _TOP_LEVEL_RANK else _NAMED_RANK fi
204
205
_candidates.add(
206
ENTRY_POINT_CANDIDATE(
207
rank,
208
symbol,
209
wrapped_location,
210
function.wraps_top_level_entry,
211
wrapped_name))
212
elif is_pragma_marked then
213
_candidates.add(ENTRY_POINT_CANDIDATE(_PRAGMA_RANK, symbol, declared_at, false, symbol.name))
214
else
215
let fault = _entry_point_shape_fault(symbol)
216
217
if !fault? then
218
_candidates.add(ENTRY_POINT_CANDIDATE(_NAMED_RANK, symbol, declared_at, false, symbol.name))
219
elif
220
_build_flags.want_executable /\
221
!_build_flags.want_library /\
222
isa Semantic.Symbols.GLOBAL_FUNCTION(symbol) /\
223
!_rejected_named?
224
then
225
// Only a global function is selected by the name: a
226
// static method of the same name is an ordinary
227
// member, as it is for the environment parameter. A
228
// library enters nowhere, so the name means nothing
229
// there either. Whether this is a fault waits for the
230
// choice - an `@entry` pragma elsewhere names the
231
// entry point over any name match, and then this
232
// declaration was never where the program starts.
233
_rejected_named = REJECTED_ENTRY_NAME(declared_at, symbol.name, fault)
234
fi
235
fi
236
237
return true
238
si
239
240
finish() is
241
let chosen mut = _choose()
242
243
// A rejected name is a fault only where nothing outranked
244
// it: with an `@entry` pragma elsewhere the program starts
245
// there and this declaration was never consulted, while a
246
// file's top-level statements rank below the name and do not
247
// stand in for it - a program that declares where it starts
248
// has said so.
249
if let rejected = _rejected_named /\ (!chosen? \/ chosen.is_top_level) then
250
_logger.error(rejected.location, "cannot start at {rejected.name}: {rejected.fault}")
251
252
_entry_name_claimed = true
253
chosen = null
254
fi
255
256
if let selected = chosen then
257
selected.symbol.is_entry_point = true
258
fi
259
260
// `--entry` excludes every top-level candidate from `_choose`,
261
// so a null result while it was given means nothing else
262
// matched the name either - not the multi-file tie the
263
// fallback message below otherwise assumes.
264
named_entry_point_not_found = !chosen? /\ _entry_point.name_is_explicit
265
266
for candidate in _candidates do
267
if !candidate.is_top_level \/ (chosen? /\ candidate.symbol == chosen.symbol) then
268
continue
269
fi
270
271
left_top_level_statements_unrun = true
272
273
_warn_unrun(candidate, chosen)
274
od
275
si
276
277
// The winner, or absent when nothing is declared or when the top
278
// rank is a tie the project is allowed to have.
279
_choose() -> ENTRY_POINT_CANDIDATE? is
280
let best: ENTRY_POINT_CANDIDATE? mut = null
281
282
for candidate in _candidates do
283
if candidate.rank == _TOP_LEVEL_RANK /\ _entry_point.name_is_explicit then
284
continue
285
fi
286
287
if !best? \/ candidate.rank < best.rank then
288
best = candidate
289
fi
290
od
291
292
if !best? then
293
return null
294
fi
295
296
let winners = Collections.LIST[ENTRY_POINT_CANDIDATE]()
297
298
for candidate in _candidates do
299
if candidate.rank == best.rank /\
300
!(candidate.rank == _TOP_LEVEL_RANK /\ _entry_point.name_is_explicit)
301
then
302
winners.add(candidate)
303
fi
304
od
305
306
if winners.count == 1 then
307
return winners[0]
308
fi
309
310
// Two files each carrying top-level statements is a shape an
311
// umbrella project has on purpose, so it selects nothing and
312
// says so per file rather than failing here.
313
if best.rank != _TOP_LEVEL_RANK then
314
for i in 1..winners.count do
315
_logger.error(
316
winners[i].location,
317
"duplicate entrypoint",
318
winners[0].location,
319
"entry point already declared here")
320
od
321
322
return winners[0]
323
fi
324
325
return null
326
si
327
328
_warn_unrun(candidate: ENTRY_POINT_CANDIDATE, chosen: ENTRY_POINT_CANDIDATE?) is
329
if _entry_name_claimed then
330
// The error at the function named as the entry point says
331
// why nothing runs; that these statements are what did
332
// not run instead is not a second fault.
333
return
334
fi
335
336
if let selected = chosen then
337
_logger.warn(
338
candidate.location,
339
UNRUN_STATEMENTS,
340
"top-level statements will not run: the entry point is {selected.display_name}",
341
selected.location,
342
"entry point declared here")
343
elif named_entry_point_not_found then
344
_logger.warn(
345
candidate.location,
346
UNRUN_STATEMENTS,
347
"top-level statements will not run: no function matches the --entry name {_entry_point.name}")
348
else
349
_logger.warn(
350
candidate.location,
351
UNRUN_STATEMENTS,
352
"top-level statements will not run: more than one file carries them and none is named with --entry")
353
fi
354
si
355
356
// Which part of this function's shape the runtime cannot enter
357
// at, or null where it can: an entry point takes no arguments or
358
// one `string[]` - a `Ghul.Environment` parameter is carried by
359
// a synthesised wrapper, which is what reaches here in its place
360
// - and returns `int` or `void`. A return type the walk has not
361
// settled yet - analysis mode leaves an unopened file's body
362
// uncompiled - is taken on trust rather than silently dropping
363
// the candidate.
364
_entry_point_shape_fault(symbol: Function) -> string? is
365
let return_type = symbol.return_type
366
367
if !return_type? then
368
return null
369
fi
370
371
let lookup = IoC.CONTAINER.instance.innate_symbol_lookup
372
373
// An asynchronous function is ruled out here too, by the
374
// task-like it returns rather than by anything else about
375
// it: neither a task nor a task-like is int or void.
376
if !return_type.matches(lookup.get_int_type()) /\ !return_type.matches(lookup.get_void_type()) then
377
return "the return type is neither int nor void"
378
fi
379
380
if symbol.arguments.count > 1 then
381
return "an entry point takes at most one string[] and one Ghul.Environment"
382
fi
383
384
if symbol.arguments.count == 1 /\
385
!symbol.arguments[0].matches(lookup.get_array_type(lookup.get_string_type()))
386
then
387
return "the parameter type is neither string[] nor Ghul.Environment"
388
fi
389
390
return null
391
si
392
393
_first_statement_location(function: Definitions.FUNCTION) -> LOCATION is
394
if let block = cast Bodies.BLOCK?(function.body) then
395
for statement in block.statements do
396
return statement.location
397
od
398
fi
399
400
return function.location
401
si
402
403
_function_for(node: Trees.Node) -> Function? is
404
let scope = _symbol_table.scope_for(node)
405
406
if !scope? then
407
return null
408
fi
409
410
return cast Function?(scope.underlying_scope)
411
si
412
si
413
414
class ENTRY_POINT_CANDIDATE(
415
rank: int,
416
symbol: Function,
417
location: LOCATION,
418
is_top_level: bool,
419
display_name: string
420
) is si
421
si