esy
package.json workflow for native development with Reason/OCaml.
This README serves as a development documentation for esy. For user
documentation refer to esy.sh documentation site.
Repository structure
The following snippet lists esy repository structured (omitting irrelevant or
obvious items) with further explanations:
├── CHANGELOG.md
├── LICENSE
├── README.md
│
├── Makefile
│ Common tasks and workflows for esy development.
│
├── bin/esy
│ symlink (wrapper on Windows) for esy command, used for running tests
│
├── bin/esyInstallRelease.js
│ postinstall step for npm releases produced with `esy npm-release`
│ command. This is a built JS file which is developed in a separate flow
│ inside `esy-install-npm-release/` subdirectory (see below).
│
├── docs
│ esy end user documentation in markdown format.
│
├── dune
├── dune-project
│
├── esy
│ This dune library implements sandbox builder - a routine which builds
│ the enture dependency graph and provides other introspection APIs.
│
├── esy/bin
│ This dune executable implements "esy" command.
│
├── esy-solve
│ This dune library implements solver.
│
├── esy-install
│ This dune library implements installer.
│
├── esy-build-package
│ This dune library implements package builder. esy library uses this to
│ build each package.
│
├── esy-build-package/bin
│ This dune executable implements "esy-build-package" command.
│
├── esy-installer
│ Implementation of installation procedure defined with *.install files.
│ This re-implements opam-installer.
│
├── esy-install-npm-release
│ Sources for `bin/esyInstallRelease.js`.
│
├── esy-command-expression
│ Parser for #{...} syntax used in esy manifests.
│
├── esy-shell-expansion
│ A simple shell expansion.
│
├── esy-yarn-lockfile
│ Parser for a subset of yarn lockfile format.
│
├── esy-lib
│ A collection of utility modules shared between other libraries.
│
├── site
│ Sources for https://esy.sh
│
├── esy.lock
├── package.json
│
├── scripts
│
├── test
│ Unit tests.
│
├── test-e2e-slow
│ End-to-end test suite which takes a significiant amount of time.
│ We execute it on CI by placing `@slowtest` token in commit messages.
│
└── test-e2e
End-to-end test suite.
Workflow
To make changes to esy and test them locally:
% git clone git://github.com/esy/esy.git
% cd esy
% esy
% yarn
% node scripts/bootstrap.js
On Linux/macOS (soon on Windows too) you can run:
% make install-githooks
which will install git hooks which will do pre commit validation.
To test the esy executable in development you can use bin/esy.
Updating bin/esyInstallRelease.js
bin/esyInstallRelease.js is developed separately within the esy-install-npm-release/ directory.
Run:
% make bin/esyInstallRelease.js
to update the bin/esyInstallRelease.js file with the latest changed, don't
forget to commit it.
Running Tests
Run:
% make test
Branches
There are two branches:
master— the active development, we cut new versions out of there regularly.0.0.x— maintainance branch for 0.0.x releases.0.2.x— maintainance branch for 0.2.x releases.0.3.x— maintainance branch for 0.3.x releases.
Workflow for esy.sh
To make changes to esy.sh:
- Bootstrap site's dev environment:
% make site-bootstrap
- Run site locally:
% make site-start
- When you are happy with the changes:
% make site-publish
Issues
Issues are tracked at esy/esy.
Publishing Releases
esy is released on npm.
Because esy is written in OCaml/Reason and compiled into a native executable we
need to acquire a set of prebuilt binaries for each supported platform (Windows,
macOS and Linux). We employ CI servers (thanks Azure) to build platform specific
releases.
The release workflow is the following:
-
Ensure you are on
masterbranch and assuming you want to release the
version currently defined inpackage.json(see step 6.), run% make release-tag % git push && git push --tags -
Wait till CI finishes its task and release
@esy-nightly/esypackage.You can test it manually.
-
Run
% make release-preparewhich downloads the nightly corresponding to the current commit working
directory is at and "promotes" it to a release. It will create
_release/packagedirectory. -
Ensure release inside
_release/packagedirectory is ok.You can
cd _release/package && npm pack && npm install -g ./esy-*.tgzto test how
release installs and feels. -
Run
% make release-publishto upload the release on npm.
Use
% make NPM_RELEASE_TAG=next release-publishto publish the release under
nexttag (so users won't get it automatically but
only explicitly requested). -
Bump version in
package.jsonto the next patch version.We expect the next version to be mostly a patch version. In case you
want to release new minor or major version you need to bump it before the
release.