Appearance
| 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 |