lfe / olp

The OLP LFE Platform ... LFE's OTP

LFE/OLP

OLP LFE Platform

Contents

• Introduction
• Dependencies
• Build Steps
• Docker
• For LFE/OLP Application Developers
• For OLP Matinainers
  • References
  • Adding New Libs
  • Updating Libs
• License

HC SVNT DRACONES ↟

WARNING: This is an experimental work in progress. The functionality offered by this codebase in creating an OLP release is base-bones, and only just in its first stages (also: no docs yet!)

LFE Upstream: The ticket that is tracking this work at a high-level from the LFE perspective is here:

• lfe/lfe#300

The OLP Project: The ticket that is tracking the tasks for getting an OLP release created is here:

• #1

There is also a Scrum-like project board here:

• https://github.com/lfe/olp/projects/1

Introduction ↟

OLP is the OLP LFE Platform, an OTP-style release build of LFE and supported community libraries, packaged together in the same way that the Erlang Runtime System and various Erlang libraries are packaged together.

Dependencies ↟

• Erlang
• git
• rebar
• relx
• make

Build Steps ↟

Preparation:

1. Clone the repo: git clone [email protected]:lfe/olp.git
2. Change directory to the olp dir: cd olp

Automated build:

1. Build: make

If you would prefer to execute the steps manually, they are as follows:

1. git submodule init
2. git submodule update
3. rebar3 release

Or, if you want to create a tarball to ship:

1. rebar3 tar

Note that if using the tar command, you don't need to run the release command.

Docker ↟

There is also a Docker option for LFE/OLP, currently built on Ubuntu 16.04:

$ docker pull lfex/olp

Running an LFE REPL in a dockerized OLP release:

$ docker run -it lfex/olp

Size comparison of Docker images:

• Ubuntu 16.04, raw: 127.2 MB
• LFE/OLP, openssl: 191.6 MB
• LFE, build tools, etc.: 879.6 MB

For LFE/OLP Application Developers ↟

There's noting to see here, yet :-) (The corageous may use OLP, but please see the map above and the reference to dragons and their whereabouts).

If you are a developer interested in what you will be able to do with OLP in the future, the following tickets may be of interest to you:

• Examine Release Use Cases
• rovide Multuple Means of OLP Installation
• tandardize Release Documentation

Once those tickets are completed, we'll have more useful information to put in this section of the README :-)

For OLP Maintainers ↟

References ↟

• https://www.rebar3.org/docs/releases
• https://github.com/erlware/relx/wiki/Configuration

Adding New Libs ↟

Assuming that the library you want to add is in the LFEX Github org, the following will add the lib as a git submodule to this project:

$ OLP_LIB=mylib make add-lib

That make target will also commit the submodule change to the repo.

Updating Libs ↟

If you already have an OLP working directory set up with LFE and libraries pulled down, but you want to bring in the latest changes (i.e., update the submodules), you can run this target:

$ make update-sources

License ↟

Apache Version 2 License

Copyright (c) 2016-2017 Robert Virding

olp's Issues

Create a repository

Part of epic #2

Examine Release Use Cases

In order to make sure that OLP is built in a manner useful for all sorts of sitiations, we need to examine the anticipated use cases (and then test OLP with those, possibly making changes during this process of discovery).

Use Cases:

• Using OLP and it's executables (lfe, lfescript, erl, erlscript) on a system with no Erlang installed
• Using OLP on a system that has Erlang installed
• Using OLP (on Erlang-less system) to develop and build LFE applications
• Using OLP (on Erlang-less system) to deploy/run one or more custom LFE applications
• Using OLP to generate a custom release that contains all of OLP but also libraries of a user's choosing

Part of release #1

Support multiple releases

Features:

• Support an LFE-only (no libs) release
• Support an LFE-essentials (just a few libs) release
• Support an LFE-web (web dev libs) release
• Support an LFE-dev (all libs) release

Part of release #1

Create an Initial Build

Features:

• Create a rebar.config file that has relx configuration info in it - #10
• Run the build to generate a release - #11
• Ensure that the appropriate dependencies are included - #19
• Esnure that appropriate olp binaries are created - #16
• Ensure that a targzball is created - #12
• Test the release in a clean environment to ensure working - #13

Part of release #1

Ensure that when running the `lfe` binary, all libs are accessible

Part of feature #16

Provide Multuple Means of OLP Installation

Features:

• Generalize work done so far to be reusable by all install methods - #38
• Default install to /opt/olp - #39
• Custom install to OLP_PREFIX (e,g., /usr/local/lib, ~/.local, etc.) - #40
• Install to Docker image - #41

Part of release #1

Create an `lfe` binary that's in the release `bin` directory

Note just lfe, though:

• lfe
• lfescript
• lfex
• lfexec
• lfedoc

Part of feature #16

Include any scripts/executables necessary to support viewing of docs by release users

Part of epic #28

Standardize Release Testing

Features:

• Devise a means for developers to test before building a release - #21
• Devise a means for developers to test a release once it has been created - #22
• Devise a means for end users to run checks/tests against a downloaded release - #23

Part of release #1

Determine tooling for build process

Part of epic #2

Run the build to generate a release

Part of epic #9

Provide a means of custom installs

Such as a make var like OLP_PREFIX which can be used to install OLP to arbitrary locations (e,g., /usr/local/lib, ~/.local, etc.)

Part of epic #37

Provide a default install to `/opt/olp`

Part of epic #37

Create a `rebar.config` file that has `relx` configuration info in it

References:

• https://www.rebar3.org/docs/releases
• https://github.com/erlware/relx/wiki/Configuration

Part of epic #9

Esnure that appropriate olp binaries are created

Tasks:

• Create an lfe binary that's in the release bin directory - #14
• Create an lfescript binary that's in the release bin directory - #17
• Ensure that when running the lfe binary, all libs are accessible - #15
• Don't create an olp binary, if possible - #18

Part of epic #9

Don't create an `olp` binary, is possible

Part of feature #16

Standardize Release Documentation

This includes a wide-ranging set of features:

• Define a standard output format for all release docs - #29
• Determine a standard way of generating LFE docs for release inclusion - #30
• Determine a standard way of generating lib docs for release inclusion - #31
• Provide an index / summary interface for easy access to LFE and library docs - #32
• Provide a unified look for all LFE and library docs - #33
• Include any scripts/executables necessary to support viewing of docs by release users - #34

Part of release #1

Establish a means of pulling in source code

Part of epic #2

Devise a means for end users to run checks/tests against a downloaded release

This would not be a task for developers, but rather for end users. As such, the mechanism selected for testing should not depend upon the development toolchain. We should only rely upon what is actually in the release itself.

As such, the following tasks might be appropriate:

• Bundle the rebar binary with the release - #24
• Ensure that the LFE tests can be run from LFE or Erlang (or use LFE/Erlang executables, e.g., ct) - #25
• Determine how to run rebar3 from "inside" the release when testing as an end user - #26
• Provide a single means of running all tests "within" the release - #27

Part of epic #20

Create Supporting Infrastructure

Features for the epic:

• Create a repository - #3
• Establish a means of pulling in source code - #4
• Determine tooling for build process - #5
• Document setup, build, and installation - #6
• Setup automated building on Travis CI - #7

Part of release #1

Ensure that the appropriate dependencies are included

Tasks:

• Examine ltest deps and add them to relx apps
• Examine lutil deps and add them to relx apps

Part of epic #9

Bundle the rebar binary with the release

We need to:

• figure out the best/common way for OTP/OLP releases to include escripts, executables, etc., in a release, and then
• include rebar3 in the release, thus allowing end users to run it (directly or indirectly)

Part of feature #23

Install OLP in a Docker image

Part of epic #37

Ensure that the LFE tests can be run from LFE or Erlang in a release

Or use LFE/Erlang executables, e.g., ct.

Part of feature #23

Determine a standard way of generating lib docs for release inclusion

Part of release #28

Generalize install code to be reusable by all install methods

OLP installs can make users' lives a bit easier:

• update PATH to point to LFE/OLP binaries
• update PATH to point to erl, erlc, etc., in the erts release dir
• start lfe and erl with the -boot parameter, pointing to the correct boot file

Right now, the only place we're installing OTP is in the experimental/testing Docker image (to /opt/olp on the guest OS). As such, we've got some custom setup in the Dockerfile -- this needs to be broken out, generalized for use by all install methods, and with the appropriate bits made optional, etc.

Tasks:

• Create bash profile inclusion for OLP installation - #42
• Update the Docker build to use this
• Create additional files as neccessary
• Update other install methods to use the same files

Part of epic #37

Setup automated building on Travis CI

Part of epic #2

Examine OTP and Follow as Example

Tasks:

• Place LFE binaries in an analogous place to where OTP places it's erl and other binaries
• Model the placement of LFE /OLP HTML docs files after where OTP puts HTML docs

Part of release #1

Document setup, build, and installation

Part of epic #2

Devise a means for developers to test a release once it has been created

Since this is for developers, the testing of the release for this type of user could rely upon the development toolchain we use to build releases.

Part of epic #20

Create an OLP Release

Epics:

• Create Supporting Infrastructure - #2
• Examine OTP and Follow as Example - #8
• Create an Initial Build - #9
• Examine Release Use Cases - #36
• Standardize Release Testing - #20
• Standardize Release Documentation - #28
• Support Multiple Releases - #35
• Provide Multuple Means of OLP Installation - #37

Provide an index / summary interface for easy access to LFE and library docs

Part of epic #28

Create an `lfescript` binary that's in the release `bin` directory

Part of feature #16

Define a standard output format for all release docs

Part of epic #28

Create bash profile inclusion for OLP installation

Right now, the docker image is the only place an OLP release is being installed (mostly for testing/prototyping purposes). However, that will not always be the case

Part of feature #38

Determine a standard way of generating LFE docs for release inclusion

Tasks:

• Generate docs in standard output format
  • before or after the release is generated?
  • probably before ...
  • how do you ensure that docs are generated with relx ... when calling rebar3 release?
• Place the generated docs in the release hierarchy ... or keep them in each project?
• Place the index file in the release hierarchy (in fact, this might be the only doc file that gets put at the olp level)
  Part of epic #28

Determine how to run `rebar3` from "inside" the release when testing as an end user

Part of feature #23

Test the release in a clean environment to ensure working

Part of epic #9

Provide a single means of running all tests "within" the release

This might be as simple as creating an lfescript or escript executable that makes all the necessary calls. This might be the best approach, as opposed to a shell script, in order to preserve the highest level of cross-platform compatibility ...

Part of feature #23

Provide a unified look for all LFE and library docs

Part of epic #28

Devise a means for developers to test before building a release

This might simply be running the unit tests in the LFE project and running rebar eunit in all ./lib/* projects.

Part of epic #20

Ensure that a targzball is created

Part of epic #9