210 lines
7.2 KiB
Plaintext
210 lines
7.2 KiB
Plaintext
# Interpreters for PIKA plugins
|
|
|
|
|
|
|
|
## About this document
|
|
|
|
This describes how PIKA invokes interpreters for PIKA plugin files.
|
|
|
|
This doesn't discuss the architecture of PIKA's interpreters,
|
|
or how to write an interpreted plugin.
|
|
|
|
The audience is mainly PIKA developers.
|
|
This may also interest users who want to use different interpreters.
|
|
|
|
|
|
## Brief summary
|
|
|
|
On Linux and MacOS, a shebang in a PIKA plugin text file
|
|
is enough to indicate what interpreter to start.
|
|
On Windows, you also need an .interp file installed with PIKA.
|
|
|
|
It can get complicated;
|
|
there are many combinations of envirnoment variables, shebangs, file suffixes, and .interp files that can work.
|
|
|
|
*To insure a PIKA interpreted plugin works across platforms,
|
|
it should have a shebang.*
|
|
|
|
*Except that ScriptFu plugin files installed to /scripts do not need a shebang
|
|
since the ScriptFu extension reads them.*
|
|
|
|
## Partial history of interpreters in PIKA
|
|
|
|
Rarely are interpreters addded to PIKA.
|
|
PIKA 2 offers Perl, Scheme, and Python2 interpreters.
|
|
PIKA 3 offers Python3, lua, javascript, and the pika-script-fu-interpreter interpreters.
|
|
|
|
|
|
## Background
|
|
|
|
An interpreter usually reads a text file.
|
|
A user often launches an interpreter and passes a text file.
|
|
But users can also double-click on a text file to launch the corresponding interpreter.
|
|
|
|
Similarly, PIKA launches an interpreter on PIKA plugin text files.
|
|
PIKA must figure out the "corresponding" interpreter.
|
|
|
|
The general mechanism for launching interpreters from their text files is built into the operating system.
|
|
On Linux and MacOS, the mechanism is called a shebang or sh-bang.
|
|
On Windows, the mechanism "associates" file extensions with programs.
|
|
|
|
PIKA uses similar mechanisms to launch interpreters.
|
|
See the code in /app/plug-ins/pikainterpreterdb.c .
|
|
*The exception is the ScriptFu extension.
|
|
PIKA starts it when PIKA starts and it reads its ".scm" plugin files from the /scripts directory without benefit
|
|
of the shebang mechanism.*
|
|
|
|
PIKA uses the mechanism when it queries plugin files at startup.
|
|
Subsequently, PIKA knows the interpreter to launch,
|
|
for example when a user clicks on a menu item implemented by an interpreter.
|
|
A user should not click on a PIKA plugin file in a file browser;
|
|
only one of the PIKA apps should launch interpreted PIKA plugin files.
|
|
|
|
|
|
## Platform differences
|
|
|
|
On Linux and MacOS, you simply need a shebang in a plugin text file.
|
|
|
|
On Windows, you must also define an .interp file.
|
|
The .interp files are part of PIKA's installation on Windows.
|
|
The .interp files are built when the Windows installer is built.
|
|
See the source file: /build/windows/installer/pika3264.iss .
|
|
|
|
A user can optionally create .interp files on Linux and MacOS.
|
|
But they are not usually part of a Linux installation.
|
|
Sophisticated users can edit .interp files to change which interpreters PIKA launches.
|
|
|
|
|
|
## shebangs
|
|
|
|
A shebang is text in the first line of a text file to be interpreted.
|
|
A shebang starts with "#!",
|
|
followed by the name or path of an interpreter,
|
|
or followed by "/usr/bin/env", a space, and the name or path of an interpreter.
|
|
|
|
!!! Shebangs for PIKA plugins always use UNIX notation, i.e. forward slashes in path strings.
|
|
Even on Windows, the shebangs are in UNIX notation.
|
|
|
|
Recommended examples for PIKA 3 (see repo directory /extensions/goat-exercises):
|
|
|
|
#!/usr/bin/env python3
|
|
#!/usr/bin/env luajit
|
|
#!/usr/bin/env gjs
|
|
#!/usr/bin/env pika-script-fu-interpreter-3.0
|
|
|
|
Other examples:
|
|
|
|
#!python
|
|
#!/usr/bin/python
|
|
#!/usr/bin/env python
|
|
|
|
Whether the other examples actually work depends on:
|
|
|
|
- the platform
|
|
- the user's environment, namely search PATH's
|
|
- any .interp files
|
|
|
|
|
|
## .interp files
|
|
|
|
Again, .interp files are necessary on Windows.
|
|
They tell PIKA which executable interpreter to launch for a PIKA plugin text file.
|
|
|
|
You usually have one .interp file for each interpreter.
|
|
For example:
|
|
- python.interp
|
|
- lua.interp
|
|
- pika-script-fu-interpreter.interp
|
|
|
|
The repo file /data/interpreters/default.interp is a non-functioning template
|
|
for a <foo>.interp file.
|
|
|
|
.interp files are installed on Windows to, for example:
|
|
|
|
C:\Users\foo\AppData\Programs\PIKA 3.0\lib\pika\3.0\interpreters
|
|
|
|
|
|
interp files have three kinds of lines:
|
|
- "program" in the form lhs=rhs
|
|
- "extension" in the "binfmt" format
|
|
- "magic" in the "binfmt" format
|
|
|
|
### "program" lines in an .interp file
|
|
|
|
These lines associate a shebang with a path to an executable.
|
|
|
|
These are in the form: "lhs=rhs"
|
|
where lhs/rhs denotes "left hand side" and "right hand side."
|
|
|
|
The lhs matches the full text of a shebang after the "#!"
|
|
For example, the lhs can be "/usr/bin/env python", having a space.
|
|
Since a shebang is always in UNIX notation, any slashes are forward.
|
|
|
|
The rhs specifies a path to an interpreter.
|
|
The rhs on the Windows platform is in Windows notation, using back slashes.
|
|
For example, the rhs can be "C:\Users\foo\AppData\Programs\PIKA 3.0\bin\python"
|
|
|
|
|
|
### "extension" lines in an .interp file
|
|
|
|
These lines associate a three-letter (sic) file extension (suffix) with a path to an executable.
|
|
|
|
These lines are in binfmt format.
|
|
See https://en.wikipedia.org/wiki/Binfmt_misc.
|
|
|
|
Informally the format is: ":name:type:offset:magic: mask:interpreter:flags"
|
|
!!! Note the field delimiter is usually ":" but can be another character.
|
|
PIKA parses the binfmt using the first character as the delimiter.
|
|
The first field is a name or identifier and has little significance.
|
|
The second field is an "E".
|
|
The third, fifth, and seventh fields are usually empty.
|
|
The fourth field is an up-to-three letter suffix.
|
|
The sixth field "interpreter" is a name or path to an executable interpreter.
|
|
|
|
If the sixth field is a Windows path that has a ":"
|
|
then the fields must be delimited with another character, say a ",".
|
|
|
|
Examples:
|
|
|
|
:python:E::py::python3:
|
|
:luajit:E::lua::luajit:
|
|
,python,E,,py,,C:\Users\foo\AppData\PIKA 3.0\bin\python3,
|
|
|
|
Note the examples are not necessarily working examples.
|
|
They might not work if the name or path is not found,
|
|
for example if luajit was not installed to the Windows system directory of executables.
|
|
|
|
Note one example shows a path in Windows notation,
|
|
having a ":", back slashes, and a space in the path.
|
|
|
|
|
|
### "magic" lines in an .interp file
|
|
|
|
These lines associate "magic" bytes (inside a binary file) with a path to an executable.
|
|
|
|
These lines are in binfmt format.
|
|
The second field is an "M".
|
|
|
|
We won't discuss these further, since they are little used.
|
|
Binary files on Windows might not have "magic" bytes.
|
|
Usually interpreters read text files, and rarely binary files.
|
|
|
|
|
|
## Building .interp files for windows
|
|
|
|
If a PIKA developer adds an interpreter to the PIKA package,
|
|
they must modify PIKA's build for Windows
|
|
to ensure proper .interp files are installed.
|
|
|
|
See the repo file: /build/windows/installer/pika3264.iss .
|
|
|
|
For the convenience of users, we usually install an .interp file having many lines.
|
|
Only one "program" line is needed if users only install canonical plugin text files
|
|
having a recommended shebang
|
|
using the actual filename of the target interpreter.
|
|
But since users may install non-canonical plugin text files by copying files,
|
|
for convenience we have more lines in the .interp file.
|
|
An extra "extension" line allows plugin text files without any shebang but a proper extension.
|
|
An extra "program" line allows plugin text files
|
|
having shebangs with alternate names for an interpreter.
|
