zephyr: Zephyr, tree-shaking for the PureScript language

[ development, library, mpl, program ] [ Propose Tags ]

Tree shaking tool and partial evaluator for PureScript CoreFn AST.


[Skip to Readme]

Flags

Automatic Flags
NameDescriptionDefault
test-with-stack

use `stack exec zephyr` in tests

Disabled
test-core-libs

test core libs

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.1.1.0, 0.1.4, 0.2.0, 0.2.1, 0.3.1, 0.3.2, 0.5.3
Change log ChangeLog.md
Dependencies aeson (>=2.0.3.0 && <2.1), ansi-terminal (>=0.11 && <0.12), ansi-wl-pprint (>=0.6.9 && <0.7), async, base (>=4.16.2 && <4.17), boxes (>=0.1.5 && <0.2), bytestring (>=0.11.3.1 && <0.12), containers (>=0.6.5.1 && <0.7), directory (>=1.3.6.2 && <1.4), filepath (>=1.4.2.2 && <1.5), formatting, Glob (>=0.10.2 && <0.11), language-javascript (==0.7.0.0), mtl (>=2.2.2 && <2.3), optparse-applicative (>=0.17.0.0 && <0.18), purescript (>=0.15.4 && <0.16), safe (>=0.3.19 && <0.4), text (>=1.2.5.0 && <1.3), transformers (>=0.5.6.2 && <0.6), unordered-containers (==0.2.19.1), utf8-string (>=1.0.2 && <1.1), zephyr (>=0.5 && <0.6) [details]
License MPL-2.0
Copyright (c) 2017-2021 Marcin Szamotulski, (c) 2022-2023 James Collier
Author Marcin Szamotulski <profunctor@pm.me>
Maintainer James Collier <jhc_at_home@proton.me>
Category Development
Home page https://github.com/MaybeJustJames/zephyr#readme
Source repo head: git clone https://github.com/MaybeJustJames/zephyr
Uploaded by MaybeJustJames at 2023-04-25T07:37:14Z
Distributions
Executables zephyr
Downloads 2461 total (20 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for zephyr-0.5.3

[back to package description]

zephyr

Maintainer: MaybeJustJames zephyr

A tree-shaking tool for PureScript. zephyr takes root terms, finds all terms which are required to evaluate them, and generates code just for them. This is done across all dependencies, and can substantially reduce the size of PureScript bundles. zephyr can also evaluate some expressions (an experimental feature).

Installation

The simplest option is to download the latest release binary. You may also build from source (see "Build & Test" section below).

Usage

# compile your project
purs compile -g corefn bower_components/purescript-*/src/**/*.purs src/**/*.purs

# run `zephyr`
zephyr -f Main.main

then you can bundle with purs bundle command:

purs bundle -o app.js -m Main dce-output/**/*.js

You can integrate it with other build tools, see below.

You can specify modules as entry points, which is the same as specifying all exported identifiers.

# include all identifiers from Data.Eq module
zephyr Data.Eq

# as above
zephyr module:Data.Eq

# include Data.Eq.Eq identifier of Data.Eq module
zephyr ident:Data.Eq.Eq

# include 'Data.Eq.eq' identifier
zephyr Data.Eq.eq

zephyr reads corefn json representation from the output directory, removes non transitive dependencies of entry points and generates common js modules (or corefn representation) to dce-output directory.

Evaluation of literal expressions

Zephyr can evaluate some literal expressions.

import Config (isProduction)

a = if isProduction
  then "api/prod/"
  else "api/dev/"

will be transformed to

a = "api/prod/"

whenever isProduction is true. This allows to have different development and production environments while still ship a minified code which only contains production code. You may define isProduction in a module under a src-prod directory and include it when compiling production code with pulp build -I src-prod and to have another copy for your development environment under src-dev where isProduction is set to false.

Integration with build tools

zephyr can be integrated with

  • pulp: use pulp build -- -g corefn to compile, and pulp browserify --skip-compile -o dce-output to bundle zephyr's output.
  • parcel
  • spago. See this example. Use spago build --purs-args '--codegen corefn,js' to compile, using spago bundle is currently affected by issue.

Build & Test

cabal build exe:zephyr

To run tests

cabal run zephyr-test

C Libraries

The released binaries are dynamically linked against glibc, so if your system is using musl (like Alpine Linux in docker) or another alternative C library, you will need to compile zephyr from source using ghc on that system.

Comments

The -f switch is not 100% safe. Upon running, zephyr will remove exports from foreign modules that seems to be not used: are not used in PureScript code and seem not to be used in the foreign module. If you simply assign to exports using JavaScript dot notation then you will be fine, but if you use square notation exports[var] in a dynamic way (i.e. var is a true variable rather than a string literal), then zephyr might remove code that shouldn't be removed.