mirror of
https://github.com/vector-im/element-desktop.git
synced 2024-09-10 06:15:17 +00:00
79 lines
3.8 KiB
Markdown
79 lines
3.8 KiB
Markdown
|
hak
|
||
|
===
|
||
|
|
||
|
This tool builds native dependencies for riot-desktop. Here follows dome very minimal
|
||
|
documentation for it.
|
||
|
|
||
|
Goals:
|
||
|
* Must build compiled native node modules in a shippable state
|
||
|
(ie. only dynamically linked against libraries that will be on the
|
||
|
target system, all unnecessary files removed).
|
||
|
* Must be able to build any native module, no matter what build system
|
||
|
it uses (electron-rebuild is supposed to do this job but only works
|
||
|
for modules that use gyp).
|
||
|
|
||
|
It's also loosely designed to be a general tool and agnostic to what it's
|
||
|
actually building. It's used here to build modules for the electron app
|
||
|
but should work equally well for building modules for normal node.
|
||
|
|
||
|
Running
|
||
|
=======
|
||
|
Hak is invoked with a command and a dependency, eg. `yarn run hak fetch matrix-seshat`.
|
||
|
If no dependencies are given, hak runs the command on all dependencies.
|
||
|
|
||
|
Files
|
||
|
=====
|
||
|
There are a lot of files involved:
|
||
|
|
||
|
* scripts/hak/... - The tool itself
|
||
|
* hak/[dependency] - Files provided by the app that tell hak how to build each of its native dependencies.
|
||
|
Contains a hak.json file and also some script files, each of which must be referenced in hak.json.
|
||
|
* .hak/ - Files generated by hak in the course of doing its job. Includes the dependency module itself and
|
||
|
any of the native dependency's native dependencies.
|
||
|
* .hak/[dependency]/build - An extracted copy of the dependency's node module used to build it.
|
||
|
* .hak/[dependency]/out - Another extracted copy of the dependency, this one contains only what will be shipped.
|
||
|
|
||
|
Workings
|
||
|
========
|
||
|
Hak works around native node modules that try to fetch or build their native component in
|
||
|
the npm 'install' phase - modules that do this will typically end up with native components
|
||
|
targeted to the build platform and the node that npm/yarn is using, which is no good for an]
|
||
|
electron app.
|
||
|
|
||
|
It does this by installing it with `--ignore-scripts` and then using `yarn link` to keep the
|
||
|
dependency module separate so yarn doesn't try to run its install / postinstall script
|
||
|
at other points (eg. whenever you `yarn add` a random other dependency).
|
||
|
|
||
|
This also means that the dependencies cannot be listed in `dependencies` or
|
||
|
`devDependencies` in the project, since this would cause npm / yarn to install them and
|
||
|
trey to fetch their native parts. Instead, they are listed in `hakDependencies` which
|
||
|
hak reads to install them for you.
|
||
|
|
||
|
Hak will *not* install dependencies for the copy of the module it links into your
|
||
|
project, so if your native module has javascript dependencies that are actually needed at
|
||
|
runtime (and not just to fetch / build the native parts), it won't work.
|
||
|
|
||
|
Hak will generate a `.yarnrc` in the project directory to set the link directory to its
|
||
|
own in the .hak directory (unless one already exists, in which case this is your problem).
|
||
|
|
||
|
Lifecycle
|
||
|
=========
|
||
|
Hak is divided into lifecycle stages, in order:
|
||
|
* fetch - Download and extract the source of the dependency
|
||
|
* link - Link the copy of the dependency into your node_modules directory
|
||
|
* fetchDeps - Fetch & extract any native dependencies required to build the module.
|
||
|
* build - The Good Stuff. Configure and build any native dependencies, then the module itself.
|
||
|
* copy - Copy the built artifact from the module build dorectory to the module output directory.
|
||
|
|
||
|
hak.json
|
||
|
========
|
||
|
The scripts section contains scripts used for lifecycle stages that need them (fetch, fetchDeps, build).
|
||
|
It also contains 'prune' and 'copy' which are globs of files to delete from the output module directory
|
||
|
and copy over from the module build directory to the output module directory, respectively.
|
||
|
|
||
|
Shortcomings
|
||
|
============
|
||
|
Hak doesn't know about dependencies between lifecycle stages, ie. it doesn't know that you need to
|
||
|
'fetch' and 'fetchDeps' before you can 'build', etc. You get to run each individually, and remember
|
||
|
the right order.
|