diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index de93fc390a02d..33b7fcf1b442d 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -26,6 +26,7 @@ sycl/ReleaseNotes.md @pvchupin @tfzhu sycl/doc/ @pvchupin @bader sycl/doc/extensions/ @intel/dpcpp-specification-reviewers sycl/doc/extensions/SPIRV/ @AlexeySotkin @bashbaug @mbelicki +sycl/doc/dev @bader @vladimirlaz # Sub-groups sycl/include/CL/sycl/detail/spirv.hpp @Pennycook @AlexeySachkov diff --git a/sycl/doc/GetStartedGuide.md b/sycl/doc/GetStartedGuide.md index 2b1c682644db3..aa6f6395e01e2 100644 --- a/sycl/doc/GetStartedGuide.md +++ b/sycl/doc/GetStartedGuide.md @@ -46,6 +46,17 @@ and a wide range of compute accelerators such as GPU and FPGA. * Windows: `Visual Studio` version 15.7 preview 4 or later - [Download](https://visualstudio.microsoft.com/downloads/) +Alternatively, you can use Docker image, that has everything you need +pre-installed: + +``` +docker run --name sycl_build -it -v /local/workspace/dir/:/src ghcr.io/intel/llvm/ubuntu2004_base /bin/bash +``` + +This command will start a terminal session, from which you can proceed with the +instructions below. See [Docker BKMs](dev/DockerBKMs.md) for more info on Docker +commands. + ### Create DPC++ workspace Throughout this document `DPCPP_HOME` denotes the path to the local directory diff --git a/sycl/doc/dev/DockerBKMs.md b/sycl/doc/dev/DockerBKMs.md new file mode 100644 index 0000000000000..928c1f82000f4 --- /dev/null +++ b/sycl/doc/dev/DockerBKMs.md @@ -0,0 +1,168 @@ +# Docker Containers BKMs + +## Installation + +Follow the [official guide](https://docs.docker.com/engine/install/) for your +OS or distro. + +### Change location of the images on the system + +By default Docker stores images in `/var/lib/docker`, but that can be changed. + +Create a new file called `/etc/docker/daemon.json` and put the following +content: + +``` +{ + "data-root": "/path/to/data/root", + "exec-root": "/path/to/exec/root" +} +``` + +### Running Docker without sudo + +Add your local user to `docker` group to be able to run docker commands without +sudo. + + +### Docker vs Podman + +Docker and Podman are very similar tools, that allow you to manage and run +container images. Unlike Docker, Podman runs without a daemon and allows you +to run containers without root permissions. The command line syntax is mostly +identical for Docker and Podman. Choose whatever is available on your system. + +## SYCL Containers overview + +The following containers are publicly available for DPC++ compiler development: + +- `ghcr.io/intel/llvm/ubuntu2004_base`: contains basic environment setup for + building DPC++ compiler from source. +- `ghcr.io/intel/llvm/ubuntu2004_intel_drivers`: contains everything from the + base container + pre-installed Intel drivers. +- `ghcr.io/intel/llvm/sycl_ubuntu2004_nightly`: contains the latest successfully + built nightly build of DPC++ compiler. The image comes in two flavors: + with pre-installed Intel drivers (`latest`) and without them (`no-drivers`). + +## Running Docker container interactively + +The main application of Docker is containerizing services. But it also allows +you to run containers interactively, so that you can use them as you would use a +terminal or SSH session. The following command allows you to do that: + +``` +docker run --name -it [:] /bin/bash +``` + +This command will download an image if it does not exist locally. If you've +downloaded an image previously, and you want to update it, use +`docker pull ` command. + +## Persisting data + +### Persisting data with volumes + +Docker container images are read-only. When container is destroyed, all its data +is lost. To persist data when working with containers (i.e. when upgrading +container version) one can use Docker volumes. + +Creating a volume: + +``` +docker volume create +``` + +Listing all volumes: + +``` +docker volume list +``` + +Mounting volume to the container: + +``` +docker run -v :/path/inside/container bash +``` + +Deleting a volume: + +``` +docker volume rm +``` + +See [official documentation](https://docs.docker.com/storage/volumes/) for more +info. + +### Passthrough a directory to a container + +Use `-v path/on/host:path/in/container` argument for `run` command to +passthrough a host directory or a file. + +## GPU passthrough + +### Intel + +Add `--device=/dev/dri` argument to `run` command to passthrough you Intel GPU. +Make sure you're a member of `video` group to be able to access GPU. + +### AMD + +Follow the [official guide](https://rocmdocs.amd.com/en/latest/ROCm_Virtualization_Containers/ROCm-Virtualization-&-Containers.html). + +### Nvidia + +Follow [these](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/user-guide.html) +instructions. + +## Changing Docker user + +By default all processes inside Docker run as root. Some LLVM or Clang tests +expect your user to be anything but root. You can change the user by specifying +`-u ` option. All Docker containers come with user `sycl` +created. + +## Managing downloaded Docker images + +List local images: +``` +docker image ls +``` + +Remove local image: +``` +docker image rm +``` + +## Managing disk usage + +See how much space is taken by docker: + +``` +docker system df +``` + +Cleaning unused data: + +``` +docker system prune +``` + +See [official documentation](https://docs.docker.com/engine/reference/commandline/system_prune/) +for more info. + +## Building a Docker Container from scratch + +Docker containers can be built with the following command: + +``` +docker build -f path/to/devops/containers/file.Dockerfile path/to/devops/ +``` + +The `ubuntu2004_preinstalled.Dockerfile` script expects `llvm_sycl.tar.xz` file +to be present in `devops/` directory. + +Containers other than base provide several configurable arguments, the most +commonly used are `base_image` and `base_tag`, which specify the base Docker +image and its tag. You can set additional arguments with `--build-arg ARG=value` +argument. + diff --git a/sycl/doc/index.rst b/sycl/doc/index.rst index 2341a77869bfa..ecff1e769e9ef 100644 --- a/sycl/doc/index.rst +++ b/sycl/doc/index.rst @@ -2,7 +2,7 @@ Data Parallel C++ Documentation =============================== Using oneAPI DPC++ for Application Development -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------------- .. toctree:: :maxdepth: 1 @@ -18,7 +18,7 @@ Using oneAPI DPC++ for Application Development EnvironmentVariables Developing oneAPI DPC++ Compiler -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- .. toctree:: :maxdepth: 1 @@ -41,3 +41,9 @@ Developing oneAPI DPC++ Compiler SYCLInstrumentationUsingXPTI ITTAnnotations +Development BKMs +~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + dev/DockerBKMs