Development
We have created several tools you can use to get started with the projects in this class. First, we’ve created a development environment in which you can do most of your command-line development (building, running, deploying). Second, we’ve created project templates that you can use to get skeleton versions of make files, docker container files, and other configuration files we will use.
Table of contents
Installation
Check out the tools project from Gerrit, into your main development directory (the directory where you will keep your git repositories):
$ cd my_projects_dir
$ git clone https://code.cs130.org/tools
Development Environment
We have a Docker image you can run on Linux (native and within Chrome OS) and MacOS with all the command-line tools and utilities referenced in these instructions pre-installed. This includes:
- Boost C++ Libraries
- Clang
- CMake
- Docker
- Google Cloud SDK
- Google Test
- Git
- git-review
- LLDB
We strongly recommend using this development environment for doing your compilation, since it will match the compilation environment used when building your projects in cloud services.
If you run into issues on your local computer, we recommend using Google Cloud Shell to develop on a Linux server in the cloud.
Starting
Run the env/start.sh script from the tools project from your main development directory with your username:
- Without IDE support
$ cd my_projects_dir $ tools/env/start.sh -u ${USER}- With IDE support
# cd my_projects_dir $ tools/env/start.sh -u ${USER} -r
This will build the development environment in Docker, and give you a shell inside the container, which will be named ${USER}_devel_env. The container will have your development directory (my_projects_dir) mapped to /usr/src/projects . From here you can build with CMake, run tests, debug with LLDB, submit code for review, or issue Google Cloud commands.
If for some reason you need to run as a different user, or multiple users, you can run multiple development environments concurrently on a single host machine, specifying different values for -u.
Additional shells
To run an additional shell in the running development environment, simply run start.sh again from another terminal:
$ tools/env/start.sh -u ${USER}
Configuration
Upon first run, the development environment will generate an SSH key for you to use with Gerrit. Follow the instructions in the terminal (look for yellow text) or at SSH Access to add your key to Gerrit.
Adding user-defined packages
User-defined packages can be specified in the form of a list of packages, one per line, in tools/user_pkg_list. For example, to add the screen package, run the following (once) before starting the development environment:
$ echo screen >> tools/user_pkg_list
Mapping ports
Additional ports can be mapped/exposed by adding additional port arguments as they would be passed to docker run. For example, to start the development environment and map the local port 8080 to port 8080 inside the development environment:
$ tools/env/start.sh [args] -- -p 127.0.0.1:8080:8080
Shutting down
The development environment should shut down automatically when all shells running against it have exited. If for some reason this does not happen, or you lose track of a shell, you can shut it down manually:
$ docker container stop ${USER}_devel_env
Using external IDEs for development
If you use an IDE for development, you can make edits directly to the files in your project directory outside the development environment, and then run compilation inside the development environment with CMake / make. Since your development directory is mapped to /usr/src/projects, you will see a consistent view of your code inside and outside of the container.
The development environment includes support for header mirroring and remote debugging for use with external IDEs, enabled by running start.sh with the -r flag.
Header mirroring
Requires -r flag
Since the development environment has specific versions of libraries installed (e.g. Boost, Google Test framework), we mirror header files into a directory named mirror at the root of your project directory. This allows header files to be accessed outside the development environment by your IDE, which should then allow navigating to class/type definitions via the IDE and enable auto-completion.
Remote debugging
Requires -r flag
With your binaries compiled for, and running inside of, the development environment, you will not be able directly debug them with your IDE. To get around this limitation, you can use the remote debugging capability of LLDB to debug binaries inside of the development environment, controlled by your host machine. To start the debugger, run start_lldb.sh in your development environment, and connect to the remote LLDB server from your IDE at localhost:7100.
See here for more instructions specific to Visual Studio Code.
Project templates
We have provided several base configuration files that you can customize for your projects.
Included files
docker/base.Dockerfile: A Dockerfile to define the base building environment for other Dockerfiles.
docker/Dockerfile: A multi-stage Dockerfile that can build, test, and create a light deployment image of your application.
.dockerignore: Starter .dockerignore file to ignore template/common files from your Docker builds.
.gitignore: Starter .gitignore file to ignore build artifacts and other generated files from being tracked by Git.
CMakeLists.txt: Starter config file for CMake that will enforce out-of-source builds, enable debug symbols, generate code coverage reports, and enable the Google Test and Boost frameworks.
cmake/CodeCoverageReportConfig.cmake: CMake include file that creates a Coverage build type and generates a test code coverage report.
docker/cloudbuild.yaml: A Google Cloud Build configuration file for use with docker/Dockerfile.
Usage
The templates/init.sh script will fill out template files for a given git repository. Typical usage to generate files for my_project:
$ cd my_project
$ ../tools/templates/init.sh
The script will look for a git repository in the current directory, or in the directory specified with the -d flag. The script uses the name of the git repository directory for the Docker image name, but this can be overridden with the -n flag. If the script is run multiple times, the user is prompted whether or not files should be overwritten. If the -f flag is passed, files are always overwritten.