requires

Definition:	requires(object x, bool bQuiet=false)
Description:	Specifies the requirements needed for a particular source code file to be executed.
pwa/p2js:	Supported. Obviously unlike desktop/phix there is no attempt to restart the browser in 64 bit mode. Valid settings for x to run in a browser are a suitable version string, or JS (aka 4), 6 (aka WIN/JS), 7 (aka WIN/LNX/JS), 8 (aka LNX/JS), or 32. Note that JavaScript is inherently a 32 bit system (cmiiw, afaik even 64-bit browsers all contain a 32-bit JS runtime), so requires(64) in a browser will always trigger a crash message.
Comments:	If x is a string, eg "0.8.2", it compares it (intelligently) against version() and displays a message and terminates execution when necessary. If x is an integer between 0 and 31, it compares it against platform() and displays a message and terminates execution when necessary. See technicalia for combinations. Otherwise x should be 32 or 64, which is compared against machine_bits() and when necessary it uses bQuiet and get_interpreter(true,{x},platform(),bPrefW) to construct a suitable replacement commandline, which it then either offers to execute when bQuiet is false (or 2), or executes automatically when bQuiet is trur (or 3), see examples and details below. In short, eg `requires(64)` is "let them know" whereas `requires(64,true)` is your "just do it", see technicalia for the minutae. If no suitable interpreter can be found it displays an appropriate message instead. You can also invoke `requires(-machine_bits())` to trigger a similar "requires restart" prompt.
Example:	requires("0.8.2") -- crashes on 0.8.1 and earlier requires(WINDOWS) -- crashes on Linux printf(1,"running %d-bit\n",machine_bits()) requires(96-machine_bits()) -- (toggle 32<==>64 [a rather daft thing to do!]) -- example output (forever in this rather silly little case): --running 32-bit --requires 64 bit: "C:\Program Files\Phix\p.exe" "C:\Program Files (x86)\Phix\test.exw" --Press Escape to abandon, Enter to retry as above... --running 64-bit --requires 32 bit: "C:\Program Files (x86)\Phix\p.exe" "C:\Program Files (x86)\Phix\test.exw" --Press Escape to abandon, Enter to retry as above... Of course the more sensible requires(32) or requires(64) would only display 0 or 1 such steps. While the prompt may be mildly annoying, and no-one in their right mind would ever code the above, it is reasonably likely a main app might start off with requires(64) but then include a component that says requires(32), or vice versa, and without the pause it would spawn alternately/madly and in all probability completely lock up the machine. For focus reasons (specifically Edita/Edix) a requires() call does not terminate until after the freshly-spawned subprocess has terminated.
Implementation:	See builtins\get_interpreter.e (an autoinclude) for details of the actual implementation, there is also a hand-translated and simplified version in p2js.js
See Also:	command_line, get_interpreter, machine_bits, platform, version
Technicalia	Note that non-existent versions may be used, for instance bugfixes and tests for new features after 0.8.3 was released were prefixed with requires("0.8.4"), in case that was urgently needed, rather than and even though the next version would (hopefully) be 1.0.0. Typically you would use one of the builtin constants such as WINDOWS, LINUX, or JS, however they are not bit-fields so special literals must be used for any combinations. Examine the builtins/get_interpreter.e source to be sure, but 0: always crash, 5: Windows or Linux (not js), 6: Windows or JavaScript (not Linux), 7: any/never crash and 8: Linux or JavaScript (not Windows) can also be used, which I think just about covers every possible permutation. Of course requires(32/64) may have nothing to do with the actual code, but availability of pre-built dlls, for example. It is perfectly possible to use a 32-bit compiler on a source containing format PE64\|ELF64 and a requires(64) statement, and vice versa, however some 64-bit constants may (rarely) end up getting cropped to 53 bits, so it is probably best to avoid that sort of thing whenever possible. Originally, before I decided to construct an alternative commandline, requires() was substituted in the front-end at compiler time like version(), and that code has been left in but commented out: it may be possible to (partially) reinstate that to at least offer a warning (an outright ban would however cripple the compiler’s own self-hosting, where such cross-compilation concerns happen to be one of the less important things the "four rounds" mechanism described in Installation happens to solve). The bQuiet parameter is only used for an x of 32 or 64 and in fact has eight possible settings: 0b000 (0/false): prompt and pass a bPrefW of -1, 0b001 (1/true): no prompt and pass a bPrefW of -1, 0b010 (2): prompt and pass a bPrefW of false, and 0b011 (3): no prompt and pass a bPrefW of false. 0b1"" (+4): optional, typically "requires(64,5) -- this runs faster on 64-bit". When the 0b100 bit is set, it quietly does nothing when no suitable/better interpreter can be found. A bPrefW of -1 means pick a p.exe or pw.exe depending on whether command_line()[1] contains a 'w'. A bPrefW of false (prefer p.exe over pw.exe), in other words a bQuiet of 2 over false, may be more appropriate given that it has already opened a console window with a prompt, even when running a gui application, so that any subsequent messages appear in that same window rather than opening up yet another one. There is possibly not much practical use for a bQuiet of 3, so that is probably best ignored, and indeed 2 is not particularly common either. False is probably the best option when publishing code, and it is obviously better to encourage long-term/frequent users to start it properly in the first place, while true can make working on it easier. You should however *never* specify a bQuiet of true (or 1/3/5/7) in any re-usable component. Should requires() detect that a `requires(32)` has already passed when `requires(64,true)` is attempted (or vice versa), then it will simply crash("would go bananas"), since otherwise it would quietly spawn processes until you ran out of memory. Be warned you could easily defeat that by using you own checks on machine_bits(), should you for some reason feel it is about time to force a hard reboot. In other words it is generally a spectacularly bad idea to call requires(), in particular with (32\|64), anywhere other than near the start of a source file, and it should always be invoked outside of any conditional statements.