From 832f1a679dbd3cacedc4bc698cd6e9ae7995e8eb Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 12 Sep 2016 14:55:46 -0700 Subject: [PATCH] Update documentation --- README.md | 6 +- docker/README.md | 120 ++++++++++++++++++++++++++++++++++++ docs/installation/docker.md | 22 ------- 3 files changed, 123 insertions(+), 25 deletions(-) create mode 100644 docker/README.md delete mode 100644 docs/installation/docker.md diff --git a/README.md b/README.md index fe27c86a10..87cfb952ca 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,8 @@ You can download and install a PowerShell package for any of the following platf | Ubuntu 16.04 | [.deb][rl-ubuntu16] | [Instructions][in-ubuntu16] | | Ubuntu 14.04 | [.deb][rl-ubuntu14] | [Instructions][in-ubuntu14] | | CentOS 7 | [.rpm][rl-centos] | [Instructions][in-centos] | -| OS X 10.11 | [.pkg][rl-macos] | [Instructions][in-macos] | -| Docker | | [Instructions] [in-docker] | +| macOS 10.11 | [.pkg][rl-macos] | [Instructions][in-macos] | +| Docker | | [Instructions][in-docker] | [rl-windows10]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.9/PowerShell_6.0.0.9-alpha.9-win10-x64.msi [rl-windows81]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.9/PowerShell_6.0.0.9-alpha.9-win81-x64.msi @@ -43,7 +43,7 @@ You can download and install a PowerShell package for any of the following platf [in-ubuntu16]: docs/installation/linux.md#ubuntu-1604 [in-centos]: docs/installation/linux.md#centos-7 [in-macos]: docs/installation/linux.md#macos-1011 -[in-docker]: docs/installation/docker.md +[in-docker]: docker To install a specific version, visit [releases](https://github.com/PowerShell/PowerShell/releases). diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000000..189e92f071 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,120 @@ +Docker +====== + +These Dockerfiles enable building and running PowerShell in a container for each Linux distribution we support. +There are two sets: stable and unstable. + +This requires an up-to-date version of Docker, such as 1.12. +It also expects you to be able to run Docker without `sudo`. +Please follow [Docker's official instructions][install] to install `docker` correctly. + +> Note: we intend to publish automatically built containers on the Docker Hub, +> but this work is still pending. + +[install]: https://docs.docker.com/engine/installation/ + +Stable +------ + +The stable containers derive from the official distribution image, +such as `centos:7`, then install dependencies, +and finally install the PowerShell package. + +At about 440 megabytes, they are decently minimal, +with their size being the sum of the base image (200 megabytes) +plus the uncompressed package (120 megabytes), +and about 120 megabytes of .NET Core and bootstrapping dependencies. + +Unstable +-------- + +The unstable containers derive from their respective stable images, +such as `powershell/powershell:stable-centos7`, +then run the `bootstrap.ps1` script which clones the repository, +runs `Start-PSBootstrap -Package` to install building and packaging tools, +runs `Start-PSBuild -Crossgen` to build PowerShell with native-image DLLs, +runs `Start-PSPackage` to generate the platform's package, +and finally installs the generated package. + +At about 4 gigabytes, +these images are *much* larger due to having all the tools installed. +This is intended so that the containers are useful for reproducing packages. + +Automation +========== + +A script, `launch.sh`, exists to automatically build all the respective images. +It has a few configuration options, +passed in as environment variables: + +* `FORK`: the fork to clone in unstable builds (default: `PowerShell`) + * Set `FORK=andschwa` to clone https://github.com/andschwa/PowerShell + +* `BRANCH`: the branch to checkout in unstable builds (default: `master`) + * Set `BRANCH=feature-A` to checkout the `feature-A` branch + +* `BUILDS`: the type of builds to run (default: `stable unstable`) + * This is order dependent! Stable images must exist for unstable images to be built + * Set `BUILDS=stable` to run the script for just the stable images + +* `DISTROS`: the distributions of Linux to run (default: `ubuntu14.04 ubuntu16.04 centos7`) + * Set `DISTROS=centos7` to build just CentOS 7 images + * Combine with `BUILDS` to filter + +* `TEST`: set to 1 to `docker run Start-PSPester` inside the containers + * The containers *must* first exist; this skips the build step + +* `BUILDARGS`: additional arguments to be passed to `docker build` during building + * Set `BUILDARGS="--no-cache"` to rebuild and ignore cached layers + +* `RUNARGS`: additional arguments to be passed to `docker run` during testing + * Set `RUNARGS="--rm"` to automatically delete the test container when finished + +For each build type (stable and unstable), +the selected distributions will run in parallel. +The output is sent to log files in `docker/logs`. +For unstable builds, the generated packages are copied to `docker/packages`. + +This script is very new, and there may be bugs. +Use `set -x` to see exactly what commands it is running. + +Examples +-------- + +To build a CentOS container with the latest released package: + +```sh +$ BUILDS=stable DISTROS=centos7 ./launch.sh +Logging to docker/logs/stable-centos7.log +Waiting for stable containers to finish; tail the logs for more information. + +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +powershell/powershell stable-centos7 f0a11a8009b7 20 minutes ago 438.3 MB +... +``` + +To generate an Ubuntu 16.04 package from andschwa's `docker` branch: + +```sh +$ DISTROS=ubuntu16.04 FORK=andschwa BRANCH=docker ./launch.sh +Logging to docker/logs/stable-ubuntu16.04.log +Waiting for stable containers to finish; tail the logs for more information. +Logging to docker/logs/unstable-ubuntu16.04.log +Waiting for unstable containers to finish; tail the logs for more information. + +$ ls packages +powershell_6.0.0-alpha.9-310-g5ded651-1ubuntu1.16.04.1_amd64.deb + +$ tail logs/unstable-ubuntu16.04.log +Step 5 : COPY bootstrap.ps1 / + ---> Using cache + ---> d18a28ff1e3d +Step 6 : RUN powershell -f bootstrap.ps1 && dpkg -i PowerShell/powershell*.deb + ---> Using cache + ---> 9cd8b1ef79b3 +Successfully built 9cd8b1ef79b3 +LOG: Saving package to docker/packages +~/src/PowerShell/docker ~/src/PowerShell/docker +'/PowerShell/powershell_6.0.0-alpha.9-310-g5ded651-1ubuntu1.16.04.1_amd64.deb' -> '/mnt/powershell_6.0.0-alpha.9-310-g5ded651-1ubuntu1.16.04.1_amd64.deb' +``` diff --git a/docs/installation/docker.md b/docs/installation/docker.md deleted file mode 100644 index 8de9b58412..0000000000 --- a/docs/installation/docker.md +++ /dev/null @@ -1,22 +0,0 @@ -Docker -====== - -Build -===== - -If you want to build it yourself: -``` -docker build -t powershell . -``` - -Run -=== - -After you have built using Docker, running PowerShell very simple: - -``` -docker run -it powershell -``` - -This Docker image is based on Ubuntu 16.04, and follows the instructions from the [Linux Installation docs][u16]. -[u16]: linux.md#ubuntu-1604