Hello World

Empirical allows you to compile your C++ to target

  • running at the command line (e.g., native machine code) and

  • running in the web browser (e.g., javascript assembly code).

This how-to aims to walk you through all the nitty gritty required to successfully compile a simple “Hello World” for both targets.

Install: Native C++ Compiler

In the Unix-verse (e.g., Linux / macOS) commonly used compilers include gcc and clang. From this point onwards, we assume that you’re working with gcc. Unless you really know what you’re doing, you’ll want to have gcc installed. The good news is: you might already!

Bring up a terminal and try entering:

which gcc

If which spits out a path, then you have gcc installed! If which says “not found,” you’ll need to go ahead and install gcc. For Linux users, your package manager (e.g., yum, apt, etc.) is probably the way to go about this. For macOS users, you’ll need to get Apple’s “Command Line Tools for Xcode.” Either way, give it a quick web search (e.g., “install gcc on [my operating system]”) and there should be plenty of how-to guides that walk you through step-by-step.

TODO Windows… Maybe you should try git for Windows (e.g., “GitBash”)?

Compile & Run: Command Line

Assuming you haven’t already pulled down a clone of Empirical, let’s get your working environment all set.

git clone https://github.com/devosoft/Empirical
cd Empirical/examples/ProjectTemplate
git submodule update --init --depth 1 --recursive

Let’s take a look at what we want to compile.

source/native/project_name.cc:

// This is the main function for the NATIVE version of this project.

#include <iostream>

#include "emp/base/vector.hpp"
#include "emp/config/command_line.hpp"

int main(int argc, char* argv[])
{
  emp::vector<std::string> args = emp::cl::args_to_strings(argc, argv);

  std::cout << "Hello World!" << std::endl;
}

This part is where Empirical source is brought in.

#include "emp/base/vector.hpp"
#include "emp/config/command_line.hpp"

The main function uses Empirical’s vector and argument parsing tools to process command line options, but doesn’t do anything with them. Then, we print “Hello World!”.

Let’s compile!

make

If you ls, you should now see the executable project_name has been created. Let’s run!

./project_name

Install: Web C++ Compiler

In order to compile for web, you’ll need the emscripten LLVM-to-Web Compiler. If you’re a new user, you (probably) don’t have this set up so we’ll walk you through step-by-step.

We aim for Empirical to track the current release of emscripten. As of mid-February 2019, Empirical is compatible with emscripten’s contemporary release, version v1.38.27. Your best bet for compiling with Empirical is to install the latest version of emscripten. However, if you run into roadblocks later on and think it might be because of breaking changes in emscripten that Empirical hasn’t tracked, let us know by posting on our issue tracker!

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest

When you want to use the emscripten compiler, you’ll want to hop over to the emsdk directory and run

source ./emsdk_env.sh

in order to load emscripten’s odds and ends into your PATH. You only need to do this once per terminal session (e.g., the first time you want to use emscripten in a terminal session).

Compile & Run: Web Browser

Assuming your working directory is still Empirical/examples/ProjectTemplate and you have loaded up emscripten (e.g., source ./emsdk_env.sh), compiling for web is a snap!

Let’s take a look at what we want to compile first, though.

source/web/project_name-web.cc:

//  This file is part of Project Name
//  Copyright (C) Michigan State University, 2017.
//  Released under the MIT Software license; see doc/LICENSE

#include "emp/web/web.hpp"

namespace UI = emp::web;

UI::Document doc("emp_base");

int main()
{
  doc << "<h1>Hello, world!</h1>";
}

The line

#include "emp/web/web.hpp"

brings in Empirical’s web tools, which provide a convenient interface for C++ code to interact with browser-y bits like html and Javascript.

The line

UI::Document doc("emp_base");

creates a persistent UI::Document object (e.g., outside the scope of the main function) that hooks into the "emp_base" div in web/project_name.html.

Then, in main, we write our message to the "emp_base" div (wrapped in some html markup formatting… e.g., <h1> and </h1>).

You can find a more comprehensive explanation of the contents of this .cpp file in our Quick Start Guide for Web Tools.

Let’s compile

make web

We should now have web/project_name.js and web/project_name.js.mem ready to go. You can verify this by entering ls web at your command line.

We’ll need to locally serve our working directory in order to view our compiled product in a web browser. Python provides a handy, no-hassle tool for this.

Try running

python3 -m http.server

at your command line. If it starts up, then great! Just leave it running for now.

If you only have Python 2 installed, try running

python -m SimpleHTTPServer

at your command line.

If you don’t have any Python installed, a step-by-step guide for your operating system is probably only a quick web search away. Alternatively, go ahead and use your web serving tool of choice.

Pop open your favorite browser and point the address bar to http://localhost:8000/web/project_name.html.

Voila!

You can end your web serving process by closing the terminal window you’re working in or entering <ctrl>-c a the command line.

Extending the Project Template

We’ve used the project template to run some simple “hello world” code natively and in the browser.

If you’re wondering how to extend the project template, we have a quick start guide on exactly that here.