diff --git a/.github/workflows/push-container-images.yml b/.github/workflows/push-container-images.yml new file mode 100644 index 00000000..e58ab25f --- /dev/null +++ b/.github/workflows/push-container-images.yml @@ -0,0 +1,45 @@ +name: push-container-images + +on: + push: + pull_request: + workflow_dispatch: + +jobs: + + build: + strategy: + matrix: + runner: + - ubuntu-latest + - ubuntu-24.04-arm + base: + - corretto-8 + - temurin-8 + - zulu-8 + - alpine-openjdk-8 + - ubuntu-openjdk-8 + - rhel-openjdk-8 + + runs-on: ${{ matrix.runner }} + permissions: + contents: read + packages: write + + steps: + + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4 + + - name: Set up Docker + uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3 + + - name: Build image + uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6 + with: + context: . + build-args: | + BASE=${{ matrix.base }} + cache-from: type=gha + cache-to: type=gha,mode=max + diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..4125bc94 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,102 @@ +# syntax=docker/dockerfile:1.16-labs + +# This is the official Ion Fusion container file (aka Dockerfile). +# +# You can build an Ion Fusion runtime image with: +# +# docker build -t fusion . +# +# Then you can run that with: +# +# docker run --rm -it fusion repl +# +# You can also build an Ion Fusion SDK image with: +# +# docker build -t fusion-sdk --target sdk . +# +# For more details, see: ./fusion/src/howto_build.md + +ARG BASE="corretto-8" +# Available BASE values: +# corretto-8 temurin-8 zulu-8 alpine-openjdk-8 ubuntu-openjdk-8 rhel-openjdk-8 + +ARG BASE_JDK="base-jdk-${BASE}" +ARG BASE_JRE="base-jre-${BASE}" + + +# Base images +# ----------- + +# Amazon Corretto OpenJDK: https://hub.docker.com/_/amazoncorretto +FROM amazoncorretto:8-al2-native-jdk@sha256:04aaf328807dfea094048b98b6cc8fcb248017c044082460248cb165c8c8dcf9 AS base-jdk-corretto-8 + +FROM amazoncorretto:8-al2-native-jre@sha256:3b9d585c1cc14d88589bee02fff1e52bf032e3af8545166fee074b6f61ad1723 AS base-jre-corretto-8 + +# Eclipse Temurin OpenJDK: https://hub.docker.com/_/eclipse-temurin +FROM eclipse-temurin:8-jdk@sha256:26eef5df6131e5da7d556f1bd62fa118571ff00c0eac6d76ae30f5c7e7ce8b49 AS base-jdk-temurin-8 + +FROM eclipse-temurin:8-jre@sha256:eb4cc550df86a3534356839ca37c5894e8dae83b29f84d7ca0684898d4057b2d AS base-jre-temurin-8 + +# Azul Zulu OpenJDK: https://hub.docker.com/r/azul/zulu-openjdk +FROM azul/zulu-openjdk:8@sha256:92f73f035d60fc0053570130c3bceba9926fb4deeecb227b45e839bd14fc0265 AS base-jdk-zulu-8 + +FROM azul/zulu-openjdk:8-jre@sha256:dbfdbd36db44b29f3b9580bec87cd41fd6962962299f3a601a314478a2f03663 AS base-jre-zulu-8 + +# Alpine Linux: https://hub.docker.com/_/alpine +FROM alpine:latest@sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715 AS base-jdk-alpine-openjdk-8 +RUN apk add --no-cache openjdk8-jdk + +FROM alpine:latest@sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715 AS base-jre-alpine-openjdk-8 +RUN apk add --no-cache openjdk8-jre + +# Ubuntu Linux: https://hub.docker.com/_/ubuntu +FROM ubuntu:latest@sha256:b59d21599a2b151e23eea5f6602f4af4d7d31c4e236d22bf0b62b86d2e386b8f AS base-jdk-ubuntu-openjdk-8 +RUN apt-get update && \ + apt-get --assume-yes --no-install-recommends install openjdk-8-jdk-headless + +FROM ubuntu:latest@sha256:b59d21599a2b151e23eea5f6602f4af4d7d31c4e236d22bf0b62b86d2e386b8f AS base-jre-ubuntu-openjdk-8 +RUN apt-get update && \ + apt-get --assume-yes --no-install-recommends install openjdk-8-jre-headless + +# Red Hat Enterprise Linux 8: https://hub.docker.com/r/redhat/ubi8 +FROM redhat/ubi8:latest@sha256:0c1757c4526cfd7fdfedc54fadf4940e7f453201de65c0fefd454f3dde117273 AS base-jdk-rhel-openjdk-8 +RUN dnf --assumeyes install java-1.8.0-openjdk-devel + +FROM redhat/ubi8:latest@sha256:0c1757c4526cfd7fdfedc54fadf4940e7f453201de65c0fefd454f3dde117273 AS base-jre-rhel-openjdk-8 +RUN dnf --assumeyes install java-1.8.0-openjdk-headless + + +# Ion Fusion build image +# ---------------------- + +FROM ${BASE_JDK} AS build +WORKDIR /opt/fusion +# avoid javadoc build errors due to encoding issues: +ENV LC_ALL="C.UTF-8" LANG="en_US.UTF-8" LANGUAGE="en_US.UTF-8" +# install gradle via the wrapper: +COPY --parents gradle/ gradlew build.gradle.kts settings.gradle.kts . +RUN ./gradlew --version +# copy in all remaining source files: +COPY --parents doc/ ftst/ fusion/ rkt/ src/ tst-data/ . +# run the gradle build, then clean up build dependencies: +RUN ./gradlew --no-daemon --console=plain --stacktrace release && rm -rf ~/.gradle + + +# Ion Fusion SDK image +# -------------------- + +FROM ${BASE_JDK} AS sdk +COPY --from=build /opt/fusion/build/install/fusion /opt/fusion +ENV PATH="/opt/fusion/bin:$PATH" +ENTRYPOINT ["fusion"] + + +# Ion Fusion runtime image +# ------------------------ + +FROM ${BASE_JRE} +COPY --from=build /opt/fusion/build/install/fusion/bin /opt/fusion/bin +COPY --from=build /opt/fusion/build/install/fusion/lib /opt/fusion/lib +ENV PATH="/opt/fusion/bin:$PATH" +ENTRYPOINT ["fusion"] + diff --git a/README.md b/README.md index ea528f22..433fba39 100644 --- a/README.md +++ b/README.md @@ -35,11 +35,10 @@ It is now an independent Apache-licensed project led by current and former Amazo # Getting Started -To learn more about this project, browse our documentation at . +To learn more about Ion Fusion, see the website: -To try out the Fusion CLI, you'll need to build from source (sorry!). -See [Building Ion Fusion](https://docs.ion-fusion.dev/howto_build.html) for instructions and -some introductory tutorials. +For more details on building the Ion Fusion SDK, the `fusion` utility, and the Ion Fusion container +images, see the documentation on [building Ion Fusion](fusion/src/howto_build.md). # Support diff --git a/fusion/src/howto_build.md b/fusion/src/howto_build.md index 85c98c52..b72cc8e4 100644 --- a/fusion/src/howto_build.md +++ b/fusion/src/howto_build.md @@ -3,39 +3,144 @@ # Building Ion Fusion -> **Prerequisites:** -> -> * Install a Java runtime, version 8 or later. We recommend [Amazon Corretto][]. -> * Install [Git][]. -> * Ensure that `java` and `git` are on your shell's `PATH`. +This guide shows how to get a working copy of the Ion Fusion source code, and +how to build the Ion Fusion software development kit (SDK) and container images. -Building from source should be straightforward: +- [Getting the source code](#getting-the-source-code) +- [Building the SDK with Gradle](#building-the-sdk-with-gradle) +- [Building the container images](#building-the-container-images) + + +## Getting the source code + +Assuming [Git][] is installed, run: git clone https://github.com/ion-fusion/fusion-java.git cd fusion-java + +Alternatively, you can download an archive of the repository's code from: + + +[Git]: https://git-scm.com/ + + +## Building the SDK with Gradle + +With a Java 8 runtime installed, you can build the Ion Fusion SDK natively +from the source directory, with: + ./gradlew release -After a successful release build, you'll have a basic SDK under `build/install/fusion`. The notable -artifacts within that directory are: +After a successful release build, you'll have a basic Ion Fusion SDK under +`build/install/fusion`, encompassing: -* `bin/fusion` is the `fusion` CLI -* `docs/fusiondoc/fusion.html` is the documentation for the Ion Fusion language -* `docs/javadoc/index.html` is the documentation embedding Ion Fusion in your Java application -* `lib` holds the jars needed for embedding +* `bin/fusion`, the Ion Fusion command-line interface (CLI) utility. +* `docs/fusiondoc/fusion.html`, the documentation for the Ion Fusion language. +* `docs/javadoc/index.html`, the documentation for the `fusion-java` API, for integrating Ion Fusion into your Java application. +* `lib/`, with the Ion Fusion JAR files required for integration. -To experiment with the CLI, add the `bin` to your path: +To experiment with the CLI, you can add the `bin` directory to your PATH: PATH=$PATH:$PWD/build/install/fusion/bin fusion help -That should give you an overview of the CLI's subcommands. +That will give you an overview of the CLI's subcommands. -## What's Next? +## Building the container images -With the `fusion` CLI ready to go, you can follow the [CLI tutorial](tutorial_cli.html) and run -some code! +With a container CLI installed (such as [docker][], [podman][], [nerdctl][], +[finch][] or [container][]) capable of building `linux/amd64` or `linux/arm64` +containers, you can build the Ion Fusion container images from the source +directory. Per your preferences, you can do this instead of, or as well as, +building Ion Fusion via Gradle as described above. +[docker]: https://www.docker.com/products/cli/ +[podman]: https://podman.io/ +[nerdctl]: https://github.com/containerd/nerdctl +[finch]: https://github.com/runfinch/finch +[container]: https://github.com/apple/container -[Amazon Corretto]: https://aws.amazon.com/corretto -[Git]: https://git-scm.com/ +### Runtime image + +The Ion Fusion runtime image is ideal for using the `fusion` CLI, and for +runtime application deployments; it is based atop an OpenJDK Java Runtime +Environment (JRE) installation, *not* a complete OpenJDK distribution. + +You can build the Ion Fusion runtime image with: + + docker build -t fusion . + +You can then run the Ion Fusion runtime image with: + + docker run --rm fusion help + +Thus, an alternative way to "install" the `fusion` CLI is simply: + + alias fusion='docker run --rm fusion` + +You can alternatively run a shell from the Ion Fusion runtime image with: + + docker run --rm -it --entrypoint sh fusion + +### SDK image + +The Ion Fusion SDK image is ideal for development and build purposes; it is +based atop a complete OpenJDK installation. + +You can build the Ion Fusion SDK image with: + + docker build -t fusion-sdk --target sdk . + +The SDK image supports building applications that integrate Ion Fusion: + + docker run --rm --entrypoint sh fusion-sdk -c ' + echo "public class Example { + public static void main(String[] args) { + dev.ionfusion.fusion.cli.Cli.main(args); + System.out.println(\"Hello, Fusion integration!\"); + } + }" >Example.java + cp="$(echo /opt/fusion/lib/*.jar | tr " " :)" + javac -cp "$cp" Example.java + java -cp ".:$cp" Example version' + +### Varying the OpenJDK + +By default, the Ion Fusion container images are built atop the official +[Amazon Corretto][] container images. + +You can alternatively build the Ion Fusion container images atop other OpenJDK +distributions, with, for example: + + docker build -t fusion --build-arg BASE=alpine-openjdk-8 + +The Ion Fusion `Dockerfile` supports a range of possible `BASE` build arguments +for controlling the underlying OpenJDK distrubution: + +- [Amazon Corretto][]: `corretto-8` +- [Eclipse Temurin](https://hub.docker.com/_/eclipse-temurin): `temurin-8` +- [Azul Zulu](https://hub.docker.com/r/azul/zulu-openjdk): `zulu-8` +- [Alpinux Linux](https://hub.docker.com/_/alpine): `alpine-openjdk-8` +- [Ubuntu Linux](https://hub.docker.com/_/ubuntu): `ubuntu-openjdk-8` +- [Red Hat Enterprise Linux 8](https://hub.docker.com/r/redhat/ubi8): + `rhel-openjdk-8` + +You can even build the Ion Fusion container images atop entirely custom JDK and +JRE base images, like: + + docker build -t fusion \ + --build-arg BASE_JDK=amazoncorretto:8-alpine-jdk \ + --build-arg BASE_JRE=amazoncorretto:8-alpine-jre \ + . + +For more details on how you can control the Ion Fusion container image build +process, see the [Dockerfile](../../Dockerfile) source code. + +[Amazon Corretto]: https://hub.docker.com/_/amazoncorretto + + +## What's Next? + +With the `fusion` CLI ready to go, you can follow the +[CLI tutorial](tutorial_cli.html) and run some code! diff --git a/fusion/src/tutorial_cli.md b/fusion/src/tutorial_cli.md index 6e44f018..5c2c1d08 100644 --- a/fusion/src/tutorial_cli.md +++ b/fusion/src/tutorial_cli.md @@ -12,7 +12,7 @@ Here we'll walk through some basic use cases with Ion Fusion's command-line inte > * Download the [Ion Fusion SDK][SDK], unpack it somewhere, and add its > `bin` directory to your `PATH`. > -> Alternatively, you can [build the CLI from source](howto_build.html). +> Alternatively, you can [build Ion Fusion from source](howto_build.html). The `fusion` CLI has three modes of operation: an interactive REPL, script execution, and direct evaluation of expressions. We'll start with the latter: