From fc3e2a36ba2ecc8dc1399519f031f960099e198b Mon Sep 17 00:00:00 2001 From: Richard Carlsson Date: Thu, 9 Jan 2025 16:09:43 +0100 Subject: [PATCH] Improve container configuration and documentation --- .devcontainer/Dockerfile | 19 +++++++-- .devcontainer/devcontainer.json | 9 ++-- Makefile | 12 +++--- README.md | 75 ++++++++++++++++++++++++--------- docker/Dockerfile | 4 ++ 5 files changed, 84 insertions(+), 35 deletions(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 9d3cc96..c3e7bc7 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -2,6 +2,9 @@ FROM erlang:27 ENV DEBIAN_FRONTEND=noninteractive +# Create a default user for the devcontainer +RUN useradd -ms /bin/bash builder + # Install dependencies RUN apt-get update && apt-get install -y \ git \ @@ -16,16 +19,21 @@ RUN apt-get update && apt-get install -y \ ruby \ ruby-dev \ asciidoctor \ + default-jre \ + graphviz \ && apt-get clean +# Additional Ruby packages +RUN gem install asciidoctor-pdf asciidoctor-diagram rouge + # Install rebar3 RUN git clone https://github.com/erlang/rebar3.git && \ cd rebar3 && \ ./bootstrap && \ ./rebar3 local install -# Set environment variable for Erlang shell history -ENV ERL_AFLAGS "-kernel shell_history enabled" +# Set Erlang flags for unicode text and shell history +ENV ERL_AFLAGS "+pc unicode -kernel shell_history enabled" # Initialize PostgreSQL database for examples USER postgres @@ -33,7 +41,10 @@ RUN /etc/init.d/postgresql start && \ psql --command "CREATE USER myuser WITH SUPERUSER PASSWORD 'mypassword';" && \ createdb -O myuser mydb -USER root +USER builder + +# stop git from complaining +RUN git config --global --add safe.directory /workspaces/theBeamBook # Set the default command to start PostgreSQL and keep the container running -CMD service postgresql start && tail -f /var/lib/postgresql/data/logfile \ No newline at end of file +CMD service postgresql start && tail -f /var/lib/postgresql/data/logfile diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 422704e..e8eb2c7 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -16,15 +16,14 @@ "ms-vscode.cpptools-extension-pack", "ms-vscode.cpptools-themes", "ms-vscode.makefile-tools", - "pgourlain.erlang", - "rebornix.ruby", + "erlang-language-platform.erlang-language-platform", "twxs.cmake", - "wingrunr21.vscode-ruby", + "editorconfig.editorconfig", + "Shopify.ruby-lsp" ] }, "settings": { "terminal.integrated.shell.linux": "/bin/bash" } - }, - "postCreateCommand": ". /workspace/venv/bin/activate && pip install -r requirements.txt" + } } \ No newline at end of file diff --git a/Makefile b/Makefile index b7b62a3..c6e9790 100755 --- a/Makefile +++ b/Makefile @@ -1,8 +1,10 @@ ASSET_CHAPTERS = $(shell find chapters -type f) -.PHONY: docker +.PHONY: all pdf html docker docker-build clean serve -all: chapters/contributors.txt beam-book.pdf index.html +all: pdf html + +pdf: beam-book.pdf chapters/contributors.txt: .git git --no-pager log | git --no-pager shortlog -s -n | awk '{$$1=""}1' | grep -v "Your Name" > $@ @@ -10,7 +12,7 @@ chapters/contributors.txt: .git beam-book.pdf: chapters/opcodes_doc.asciidoc book.asciidoc chapters/contributors.txt $(ASSET_CHAPTERS) asciidoctor-pdf -r ./style/custom-pdf-converter.rb -r asciidoctor-diagram -r ./style/custom-admonition-block.rb -a config=./style/ditaa.cfg --doctype=book -a pdf-style=./style/pdf-theme.yml book.asciidoc -o $@ -index.html: $(ASSET_CHAPTERS) +html: chapters/contributors.txt $(ASSET_CHAPTERS) cp -r images site asciidoctor -r asciidoctor-diagram -r ./style/custom-admonition-block.rb -a config=style/ditaa.cfg --backend=html5 --doctype=book -o site/index.html book.asciidoc --trace rsync -R code/*/*.png site @@ -27,8 +29,8 @@ genop.tab: clean: find site -type f -name '.[^gitignore]*' -delete - rm -rfv beam-book.pdf site/index.html site/*.png site/*.md5 xml/*.png xml/*.md5 xml/beam-book-from-ab.xml ./images/diag-*.png site/code/*/*.png site/images/* - rmdir site/code/* site/images site/code + rm -f beam-book.pdf site/index.html site/*.png site/*.md5 xml/*.png xml/*.md5 xml/beam-book-from-ab.xml images/diag-*.png + rm -rf site/code site/images .asciidoctor site/.asciidoctor serve: all cd site && python3 -m http.server diff --git a/README.md b/README.md index 76beefd..f031310 100644 --- a/README.md +++ b/README.md @@ -136,29 +136,73 @@ an issue declaring what you intend to do. ## Building the PDF locally from source -The project contains a makefile which +The project contains a Makefile which will let you build your own PDF from the source, provided -that you have all the needed tools installed. +that you have all the needed tools installed. Just running +the command +```shell +make +``` +will build the file `beam-book.pdf` in the top directory +as well as the HTML version under the `site` directory. + +We assume that you already have an Erlang installation of +your choice for running examples etc. Apart from that, see +below for what you need in order to build the book. ### Docker -You can build the project locally using docker by first building the docker image -``` +You can build the project locally via Docker without having to +install any addtional software, by first building the docker + image. Assuming you have Docker installed, run: +```shell make docker-build ``` -And then building the project by -``` +And then you can build the book by running +```shell make docker ``` +(Note: On Linux, the resulting files will be created with +User ID 1000, regardless of what your current user ID is +outside Docker. This is due to how Docker integrates with +the file system.) + +#### Devcontainers in the IDE + +If you use VSCode or any other editor that has support for +Devcontainers, this repository contains a configuration that +can be used out of the box. By opening the project in the dev +container, you get a shell inside the container with all the +tools pre-installed and with access to the project files so +that all you need to do is run `make`. + +For a tutorial on devcontainers, see +[Introduction to Dev Containers](https://happihacking.com/blog/posts/2023/dev-containers/), +[Decvontainer setup](https://happihacking.com/blog/posts/2023/dev-containers-emacs/), +and [Devcontainers, UIDs and file permissions](https://happihacking.com/blog/posts/2024/dev-containers-uids/). + +If you prefer to build natively rather than use Docker, +see the following sections depending on your system. ### Linux -WIP, to be updated -```shell -make -``` + +The following should work on a Debian based system, such as Ubuntu: +1. `apt install git rsync wget curl make` +1. `apt install ruby ruby-dev default-jre` +1. `apt install asciidoctor graphviz` +1. `gem install asciidoctor-pdf asciidoctor-diagram rouge` +1. `make` ### Mac OSX +#### Using Homebrew + +1. `brew install asciidoctor graphviz wget ditaa` +1. `gem install asciidoctor-pdf asciidoctor-diagram rouge` +1. `make` + +#### Manual installation + 1. Install [asciidoc](https://github.com/asciidoctor/asciidoctor) 1. Install [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf) 1. Install [asciidoctor-diagram](http://asciidoctor.org/docs/asciidoctor-diagram/) @@ -168,17 +212,6 @@ make 1. Install [wget](https://www.gnu.org/software/wget/) 1. `make` -### Mac OSX (using brew etc) - -1. `brew install asciidoctor` -1. `gem install asciidoctor-pdf` -1. `gem install asciidoctor-diagram` -1. `brew install ditaa` -1. `brew install graphviz` -1. `gem install rouge` -1. `brew install wget` -1. `make` - ## License _The Erlang Runtime System_ by Erik Stenman is licensed under a diff --git a/docker/Dockerfile b/docker/Dockerfile index 1128021..923e676 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -1,10 +1,14 @@ FROM asciidoctor/docker-asciidoctor:latest +# Create a default user instead of root +RUN adduser --disabled-password --shell /bin/bash builder + RUN apk add --no-cache\ git\ rsync\ erlang +USER builder RUN git config --global --add safe.directory /documents WORKDIR /documents CMD ["make"]