add Dockerfile; update docs

Dockerfile

@@ -0,0 +1,75 @@
+################################################################################
+## Dockerfile for RISC-V Atom                                                 ##
+################################################################################
+
+FROM ubuntu:20.04
+LABEL version=0.1
+LABEL description="Docker image for RVAtom environment on ubuntu 18.04"
+
+################################################################################
+## Environment Setup
+
+# Setup basic linux env
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    sudo curl git vim nano build-essential ccache python3 python3-pip python-is-python3
+
+# Add new user
+# Create a user named "dev" and add to sudo group
+RUN useradd -m dev && echo "dev:dev" | chpasswd && adduser dev sudo
+WORKDIR /home/dev
+
+# Setup bashrc
+RUN curl -L https://gist.githubusercontent.com/saursin/79f60ec68f18fca893848971f4f7e730/raw/b218463c7e001e8f20355d0172c609a11eda3f30/bashrc -o .bashrc
+
+################################################################################
+## RISC-V Atom Dev Setup
+
+# Install packages
+RUN apt-get install -y --no-install-recommends \
+    screen libreadline-dev
+RUN pip3 install gdown
+
+# Install RISC-V Toolchain
+ARG RVTOOLCHAIN_PREBUILT_FILEID=1kSxCHqrfe7jrk32N3W_e1YbHj97-EsaN
+ARG RVTOOLCHAIN_TAR=rv64_mutilib.tar.gz
+ARG RVTOOLCHAIN_INSTALL_PATH=/opt/riscv
+
+RUN gdown $RVTOOLCHAIN_PREBUILT_FILEID -O $RVTOOLCHAIN_TAR
+RUN mkdir -p $RVTOOLCHAIN_INSTALL_PATH
+RUN tar -xvf $RVTOOLCHAIN_TAR -C $RVTOOLCHAIN_INSTALL_PATH && rm -f $RVTOOLCHAIN_TAR
+
+# Install Verilator
+ARG VERILATOR_PREBUILT_FILEID=1rXszcRib7oryDU2sMhZpPxMn5Ev3RbxG
+ARG VERILATOR_TAR=verilator_5p006.tar.gz
+ARG VERILATOR_INSTALL_PATH=/opt/verilator
+
+RUN gdown $VERILATOR_PREBUILT_FILEID -O $VERILATOR_TAR
+RUN mkdir -p $VERILATOR_INSTALL_PATH
+RUN tar -xvf $VERILATOR_TAR -C $VERILATOR_INSTALL_PATH && rm -f $VERILATOR_TAR
+
+# Add tools to PATH
+ENV PATH=$VERILATOR_INSTALL_PATH/bin:$PATH
+ENV PATH=$RVTOOLCHAIN_INSTALL_PATH/bin:$PATH
+
+################################################################################
+## Setup Repository
+
+# switch to dev user
+USER dev
+WORKDIR /home/dev
+
+# Setup repo
+ARG RVATOM=/home/dev/riscv-atom
+
+# Clone the repo
+RUN cd ~ && git clone https://github.com/saursin/riscv-atom.git
+
+# Install repo-specific python packages
+RUN pip3 install -r $RVATOM/requirements.txt
+
+# Add sourceme to bashrc
+RUN cat <<EOT >> .bashrc
+source $RVATOM/sourceme
+echo "*** Welcome to the riscv-atom container! ***"
+EOT

docs/pages/getting_started/docker.rst

@@ -2,37 +2,57 @@ RISC-V Atom Development in Docker
 ##################################
 
 Alternative to previous approach, you can also use the provided `Dockerfile <https://github.com/saursin/riscv-atom/blob/main/Dockerfile>`_
-to build a Docker image containing all the necessary tools to checkout the RISC-V Atom project. As a prerequisite, you
-must have Docker installed on your system. You can install Docker by following the `official Docker guide <https://docs.docker.com/desktop/>`_.
+to build a Docker image containing all the necessary tools to checkout the RISC-V Atom project. This approach is OS agnostic.
+As a prerequisite, you must have Docker installed on your system. You can install Docker by following the
+`official Docker guide <https://docs.docker.com/desktop/>`_.
 
-Once you have installed Docker, you can clone the RISC-V Atom repository and build the Docker image as follows.
+Once you have installed Docker, you can follow these steps to setup a RISC-V Atom dev environment.
+
+.. tip::
+  We recommend using bash is you have a Linux OS and powershell if you're on Windows.
+
+
+1. Obtain the Dockerfile from the RISC-V Atom repository either manually or by using the following command.
 
 .. code-block:: bash
+  
+  $ wget https://raw.githubusercontent.com/saursin/riscv-atom/main/Dockerfile
+  $ ls                                              # check if the file was downloaded
 
-    $ git clone https://github.com/saursin/riscv-atom.git
-    $ cd riscv-atom                         # switch to riscv-atom directory
-    $ docker build . -t rvatom-dev          # we'll name this image rvatom-dev
- 
-Once the build is finished you should be able to see the image using the following command:
+2. Once you have the Dockerfile, we need to build a docker image as follows.
 
 .. code-block:: bash
 
-    $ docker images
-    REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
-    rvatom-dev   latest    a9cab48034fc   24 hours ago   475MB
+  $ docker build . -t rvatom-dev-img                # We'll call this image rvatom-dev-img
+  $ docker images                                   # List docker images
+  REPOSITORY       TAG       IMAGE ID       CREATED          SIZE
+  rvatom-dev-img   latest    4e888efaf4c1   3 minutes ago    2.46GB
 
-To run an instance of this docker image (also called container), you can run the following command.
+4. Now we can create a new instance of this image (aka container) called ``rvatom`` from ``rvatom-dev-img`` image as follows.
 
 .. code-block:: bash
 
-    $ docker run -it -v .:/home/riscv-atom rvatom-dev
-    > Setting environment variables...
-    *** Welcome to the riscv-atom container! ***
-    root@7110d3ddecd7:/home/riscv-atom#
+  $ docker create -it --name rvatom rvatom-dev-img  # We'll call this container rvatom
+  $ docker ps -a                                    # List all containers (running or not running)
+  CONTAINER ID   IMAGE            COMMAND       CREATED         STATUS    PORTS     NAMES
+  5a1a95325d61   rvatom-dev-img   "/bin/bash"   5 seconds ago   Created             rvatom
+
+5. At this point, we're all set to start our new docker container as follows!
 
-The above command should launch the container and attach to it, and you should have a familiar linux prompt! It will 
-also mount the riscv-atom directory on host machine to ``/home/riscv-atom`` directory in the container, and
-automatically set-up the environment variables for RISC-V Atom development.
+.. code-block:: bash
+  
+  $ docker start -i rvatom
+  ***** RISC-V Atom Environment Setup *****
+  > Setting environment variables...
+  Found Verilator at: /opt/verilator
+  *** Welcome to the riscv-atom container! ***
+  ~@dev $
+
+You should be able to see a bash prompt, and the riscv-atom repository already cloned for you in the home folder!
+
+.. tip::
+  You can detach from the container using :kbd:`ctrl` + :kbd:`d` or by using the ``exit`` command. This also stops the
+  container. To restart, simpy use the above ``docker start`` command again.
 
 .. tip::
-    Checkout this `cheatsheet <https://docs.docker.com/get-started/docker_cheatsheet.pdf>`_ to learn more about Docker CLI syntax.
+  Checkout this `cheatsheet <https://docs.docker.com/get-started/docker_cheatsheet.pdf>`_ to learn more about Docker CLI syntax.