C Playground is an online sandbox that makes it easy to quickly test out C or C++ code. A specific goal of the project is to offer strong support for OS constructs such as multiprocessing and multithreading.
Contributions are welcome! (I would really appreciate your help!) Here is a short guide on how to contribute to open-source software on Github.
Here are some things you should know:
- If you're looking for something to help with, check out the issues tracker. Issues are generally tagged by priority, difficulty, and skill set, so you can find something that would be interesting and suitable to work on.
- Before you start working on something, please comment on the relevant GitHub issue. That way, no one else duplicates your work, and I can provide more context for the issue or clarify any issues that come up.
- We have a C Playground Slack where we discuss C Playground development. Email me if you'd like to join.
- If you haven't done web development before, WebStorm is my favorite web IDE and may save you a lot of time, as much of this project is written in TypeScript, allowing a solid IDE to give you helpful hints. If you're a student, you can download it for free.
I am always happy to help and answer questions! Even if you've done this before and know how to find your way around a project, please reach out to say hi -- I would love to hear from you!
Unfortunately, C Playground is pretty tightly coupled to its execution environment, as the debugger in C Playground depends on a modified Linux kernel. It is possible to run C Playground with its debugger disabled on other operating systems, and you should look at Manual setup instructions if you'd like to do this. However, it is simplest to run C Playground inside of a virtual machine for development purposes. We use Vagrant to manage the virtual machine, which makes setup extremely easy.
You should install Virtualbox and Vagrant. On Mac, you can do this using homebrew:
brew cask install vagrant virtualbox
On Ubuntu, using apt:
sudo apt install virtualbox vagrant
Once you have Vagrant and Virtualbox installed, you can create the virtual machine:
# first, cd to cplayground directory.
vagrant plugin install vagrant-reload
vagrant up
This will take a while (on the order of 10 minutes). You only need to do this
once, although you can run vagrant destroy and vagrant up again to recreate
the VM if your environment somehow becomes really messed up.
Vagrant automatically mounts the cplayground directory in the VM as a shared folder. You can edit the source code on your host machine using your editor of choice, and your changes will be reflected from within the VM without any action on your part.
Once the VM is provisioned and running, you can start the C Playground server:
# SSH into the VM
vagrant ssh
# Once in the VM, start the server. The backend does not have hot reloading,
# so if you change server code, you should rerun "yarn run serve".
yarn run serve
Now, you can visit http://localhost:3000/, and C Playground should load.
That's it!
If you restart your computer, the VM will be shut down. You may run vagrant up to start the VM again. This will be much faster than the first vagrant up, since it won't re-install all the dependencies.
If you're working on a machine with limited memory, you can run vagrant suspend to stop the VM when you aren't working on it. vagrant up will resume
the VM.
If you are working on frontend code, in addition to starting the server, you may also want to run a watch script that will recompile the Typescript and CSS when it is changed. In another terminal window:
vagrant ssh
yarn run watch-client
Running yarn run serve recompiles the backend code and starts the server.
Unfortunately, there is currently no hot-reloading (although this would be a
nice contribution if you have time), so you'll need to rerun this command each
time you change something in the backend server code.
If you change anything in src/server/docker-image/, you will need to rebuild
the Docker container:
# in the vm (vagrant ssh)
docker build -t cplayground src/server/docker-image/
C Playground uses a loadable kernel module to obtain data for its debugger's execution diagrams. If you make a change, you can rebuild and reload the kernel module like so:
cd src/server/kernel-mod
# Build the kernel module
make
# Unload the module, if it has already been loaded
rmmod cplayground
# Load the recompiled module
insmod cplayground.ko
If something goes wrong, the kernel logs will be very useful. You can see them
by running dmesg or by having a look at /var/log/kern.log.
C Playground also uses a modified Linux kernel. You shouldn't need to rebuild
the kernel, but if you do, you can cd to src/server/kernel and run
build-kernel.sh. This will produce a series of .deb files, which you can
install using dpkg (the setup scripts do this
here).
I have only tested these instructions on Ubuntu, but they should work on other Linux flavors with modification.
Install NodeJS:
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get install -y nodejs
Install and configure Docker:
sudo apt install apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
sudo apt update
sudo apt install docker-ce
You will probably want to add the user running cplayground to the docker group,
so that you don't need to run the server as root:
sudo usermod -aG docker $USER
In order to support memory limits on containers (highly recommended to limit
DDoS attacks), you need to edit /etc/default/grub and modify the
GRUB_CMDLINE_LINUX variable:
GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"
Then:
sudo update-grub
sudo reboot
Install project dependencies and build:
sudo apt-get install -y build-essential make
cd cplayground/
yarn install
sudo docker build -t cplayground src/server/docker-image/
yarn run build
Create a MySQL database called cplayground and add a user for this database.
Then run the server:
export DB_URL="mysql://username:password@localhost"
node src/server/migrations.js up
yarn run serve