mirror of
https://github.com/idris-lang/Idris2.git
synced 2024-09-11 13:36:08 +03:00
[docs] javascript FFIs and packaging of JS or C support files (#2842)
* Add documentation on javascript FFIs and packaging of JS or C support files. * Add to changelog. * line length * add some detail about the install directories for packages.
This commit is contained in:
parent
8db12f5a49
commit
63a22b819d
@ -70,6 +70,12 @@
|
||||
* Changes `getNProcessors` to return the number of online processors rather than
|
||||
the number of configured processors.
|
||||
|
||||
### Other Changes
|
||||
* The `data` subfolder of an installed or local dependency package is now automatically
|
||||
recognized as a "data" directory by Idris 2. See the
|
||||
[documentation on Packages](https://idris2.readthedocs.io/en/latest/reference/packages.html)
|
||||
for details.
|
||||
|
||||
## v0.6.0
|
||||
|
||||
### REPL changes
|
||||
|
@ -27,7 +27,7 @@ the library. In this document, we will assume the default Chez Scheme code
|
||||
generator (the examples also work with the Racket or Gambit code generator) and
|
||||
that the foreign language is C.
|
||||
|
||||
Scheme Sidenote
|
||||
Scheme Details
|
||||
---------------
|
||||
|
||||
Scheme foreign specifiers can be written to target particular flavors.
|
||||
@ -60,6 +60,33 @@ the individual backends.
|
||||
The standard C backend is known as "RefC", and uses the ``RefC`` language
|
||||
specifier.
|
||||
|
||||
Javascript Details
|
||||
-------------------
|
||||
|
||||
Javascript foreign specifiers can be written to target ``browser``, ``node``,
|
||||
or ``javascript``. The former two are mutually exclusive while ``javascript``
|
||||
FFI specifiers apply both when building for the browser and when building for
|
||||
NodeJS.
|
||||
|
||||
Javascript specifiers must be further specialized as ``lambda``, ``support``,
|
||||
or ``stringIterator``.
|
||||
|
||||
The syntax, therefore, is ``node:lambda:some_func`` (for the NodeJS-specific
|
||||
FFI and a lambda that executes a function named ``some_func``).
|
||||
|
||||
When using the ``support`` option, you also specify the name of the support
|
||||
file. Idris will look in all ``data`` directories under a ``js`` subfolder
|
||||
for a file with this name. These file names should be distinct for your
|
||||
project so they don't collide with support files from other projects
|
||||
further on in the build process for an executable. Suppose your package is
|
||||
named "http-idris" and you have FFI specifiers like
|
||||
``node:support:http_request,http_idris`` in your Idris code. You should make
|
||||
sure a data directory in scope has a ``js`` directory with an
|
||||
``http_idris.js`` file in it. Another important note is that functions
|
||||
within this file must be prefixed with ``http_idris_``; therefore, the
|
||||
function referred to in the example we give here would need to be named
|
||||
``http_idris_http_request`` in the ``http_idris.js`` support file.
|
||||
|
||||
FFI Example
|
||||
-----------
|
||||
|
||||
|
@ -162,3 +162,51 @@ package will then be located as follows:
|
||||
In each case, if more than one version satisfies the constraint, it will choose
|
||||
the one with the highest version number.
|
||||
If package versions are omitted in directory names, they are treated as the version ``0``.
|
||||
|
||||
Support file install directories
|
||||
================================
|
||||
|
||||
As noted above, packages can be installed globally or locally to be used as dependencies in
|
||||
other projects. In either case, there are two directories within a package's install root that
|
||||
Idris 2 treats specially when the package is depended upon by some other Idris package.
|
||||
|
||||
Those directories are ``lib`` and ``data``.
|
||||
|
||||
Below we will refer to these directories as ``pkgname-<version>/lib`` and ``pkgname-<version>/data``
|
||||
and in all cases these folders may be located locally in the depending project within a ``depends``
|
||||
directory or globally (you can ask Idris 2 for the global install directory with ``idris2 --libdir``).
|
||||
|
||||
Library files
|
||||
-------------
|
||||
|
||||
Idris will look for library files at ``pkgname-<version>/lib``. Library files are those that
|
||||
will need to be around whenever an executable that depends on your library is run. That is,
|
||||
these files are not built into the executable, but rather linked against or otherwise referred
|
||||
to during building and then loaded in at runtime. A common example of this type of file is a
|
||||
shared object file (these commonly have the extension ``.so`` on Linux systems and ``.dylib`` on Mac OS
|
||||
systems).
|
||||
|
||||
When building with the Scheme or Refc backends, you may want your package to use Idris 2's ``C`` FFI
|
||||
and rely on a ``C`` support file. The FFI interface is documented elsewhere so we won't go into that
|
||||
here. Once you do have a support file written in ``C``, you can build an ``so`` file using your
|
||||
package's post-build hook. Then, install (copy) that ``so`` file into the ``lib`` subfolder where
|
||||
Idris has installed your package in your post-install hook. When an executable depends on your package,
|
||||
Idris will copy shared object files from the ``lib`` directory into the build folder for the exectuable.
|
||||
|
||||
Data files
|
||||
----------
|
||||
|
||||
Idris will look for data files at ``pkgname-<version>/data``. Data files are a bit open-ended
|
||||
in how they are used. One important use-case is adding support files for the ``Javascript`` FFI.
|
||||
``Javascript`` support files are different from ``C`` support files in that they get built *into* the
|
||||
executable rather than installed alongside it. The FFI interface is documented elsewhere, but we will
|
||||
briefly touch on the subject to describe the end-to-end packaging of JS support files using the
|
||||
``data`` directory.
|
||||
|
||||
When building with the NodeJS backend, you can refer to functions you've defined in external
|
||||
support JS files by using the FFI pattern ``node:support:my_func,my_lib``. This pattern will prompt
|
||||
idris to look in any ``data`` directories it knows about for a ``js`` folder and a file named
|
||||
``my_lib.js`` within it. So, you can specify a post-install hook for your package that copies any
|
||||
needed support JS files into the ``pkgname-<version>/data/js`` folder to enable Idris to later build
|
||||
that support file into any JS executables that depend on your package.
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user