diff --git a/ChangeLog.md b/ChangeLog.md new file mode 100644 --- /dev/null +++ b/ChangeLog.md @@ -0,0 +1,3 @@ +# Verison v0.3.2 +- Copy foreign modules from source directories if they are not present in the + `output` directory. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -2,28 +2,30 @@ [![Maintainer: coot](https://img.shields.io/badge/maintainer-coot-lightgrey.svg)](http://github.com/coot) ![zephyr](https://github.com/coot/zephyr/workflows/Haskell%20CI/badge.svg) -An experimental tree-shaking tool for [PureScript](https://github.com/purescript/purescript). +A tree-shaking tool for [PureScript](https://github.com/purescript/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). # Usage ```sh -# compile your project (or use `pulp build -- -g corefn`) +# compile your project purs compile -g corefn bower_components/purescript-*/src/**/*.purs src/**/*.purs # run `zephyr` zephyr -f Main.main - -# bundle your code -webpack ``` - -or you can bundle with `pulp`: +then you can bundle with `purs bundle` command: ```sh -pulp browserify --skip-compile -o dce-output -t app.js +purs bundle -o app.js -m Main dce-output/**/*.js ``` +You can integrate it with other build tools, see +[below](#Integration-with-build-tools). -You can also specify modules as entry points, which is the same as specifying -all exported identifiers. +You can specify modules as entry points, which is the same as specifying all +exported identifiers. ```sh # include all identifiers from Data.Eq module @@ -35,15 +37,15 @@ # include Data.Eq.Eq identifier of Data.Eq module zephyr ident:Data.Eq.Eq -# include Data.Eq.eq identifier (not the lower case of the identifier!) +# include 'Data.Eq.eq' identifier zephyr Data.Eq.eq ``` -`zephyr` reads corefn json representation from `output` directory, removes non -transitive dependencies of entry points and dumps common js modules (or corefn -representation) to `dce-output` directory. +`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. -# Zephyr eval +# Evaluation of literal expressions Zephyr can evaluate some literal expressions. ```purescript @@ -57,13 +59,27 @@ ```purescript a = "api/prod/" ``` -whenever `isProduction` is `true`. This allows you to have different -development and production environment while still ship a minified code in your -production environment. You may define `isProduction` in a module under +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](https://github.com/purescript-contrib/pulp): use + `pulp build -- -g corefn` to compile, and `pulp browserify --skip-compile -o dce-output` + to bundle `zephyr`'s output. +* [parcel](https://github.com/parcel-bundler/parcel) +* [spago](https://github.com/purescript/spago). See + [this](https://github.com/thomashoneyman/purescript-halogen-realworld) + example. Use `spago build --purs-args '--codegen corefn'` to compile, using + `spago bundle` is currently affected by + [issue](https://github.com/purescript/spago/issues/216). + # Build & Test ```sh @@ -79,12 +95,9 @@ # 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 +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 +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 +than a string literal), then `zephyr` might remove code that shouldn't be removed. - -The best practice is to run a JavaScript tree-shaking algorithm via `webpack` or -`rollup` on the JavaScript code that is pulled in your bundle by foreign imports. diff --git a/app/Command/Run.hs b/app/Command/Run.hs --- a/app/Command/Run.hs +++ b/app/Command/Run.hs @@ -48,7 +48,8 @@ import qualified Language.PureScript.CoreFn.FromJSON as CoreFn import qualified Language.PureScript.Errors.JSON as P import qualified System.Console.ANSI as ANSI -import System.Directory (copyFile, doesDirectoryExist, getCurrentDirectory, removeFile) +import System.Directory (copyFile, doesDirectoryExist, doesFileExist, + getCurrentDirectory, removeFile) import System.Exit (exitFailure, exitSuccess) import System.FilePath ((), (-<.>)) import System.FilePath.Glob (compile, globDir1) @@ -279,10 +280,12 @@ in BSL.writeFile foreignFile (TE.encodeUtf8 $ JS.renderToText jsAst') Right _ -> return () - Just _path -> do + Just path -> do let filePath = T.unpack (P.runModuleName moduleName) - copyFile (optInputDir filePath "foreign.js") - (optOutputDir filePath "foreign.js") + outputPath = optInputDir filePath "foreign.js" + -- prefer foreign module in 'optOutputDir'. + bool path outputPath <$> doesFileExist outputPath + >>= (`copyFile` (optOutputDir filePath "foreign.js")) Nothing -> pure () } diff --git a/zephyr.cabal b/zephyr.cabal --- a/zephyr.cabal +++ b/zephyr.cabal @@ -1,5 +1,5 @@ cabal-version: 2.0 -version: 0.3.1 +version: 0.3.2 name: zephyr synopsis: Zephyr, tree-shaking for the PureScript language @@ -13,7 +13,9 @@ maintainer: Marcin Szamotulski copyright: (c) 2017-2018 Marcin Szamotulski build-type: Simple -extra-source-files: README.md +extra-source-files: + ChangeLog.md + README.md category: Development tested-with: ghc @@ -66,7 +68,7 @@ , boxes ^>=0.1.4 , containers , formatting - , language-javascript ^>=0.7 + , language-javascript ^>=0.7.1 , mtl >=2.1.0 && <2.3.0 , purescript ^>=0.13.8 , safe ^>=0.3.9