Merge branch 'master' of https://github.com/devosoft/Empirical

README.md

@@ -4,15 +4,15 @@ is simple to incorporate into existing projects.
 
 [![Build Status](https://travis-ci.org/devosoft/Empirical.svg?branch=master)](https://travis-ci.org/devosoft/Empirical) [![Documentation Status](https://readthedocs.org/projects/empirical/badge/?version=latest)](https://empirical.readthedocs.io/en/latest/?badge=latest)
 
-See the doc/QuickStartGuides/ folder to start using the library.
+See our [Quick Start Guides](https://empirical.readthedocs.io/en/latest/QuickStartGuides) to start using the library.
 
 Tools in Empirical include:
 * Web-enabled elements to facilitate compiling to JavaScript and with a full web interfaces,
   using Mozilla's Emscripten compiler (from C++ to high-efficiency JavaScript).
 * Debug tools to facilitate audited memory management; these tools are turned off outside of
   debug mode allowing the full speed of raw pointers and normal standard library components.
 * A wide range of Helper tools to streamline common scientific computing tasks such as
-  configuration, data mangement, mathematical manipulations, etc.
+  configuration, data management, mathematical manipulations, etc.
   All of these are designed to be  easy-to-use and efficient.
 * A powerful set of evolution tools for building Artificial Life or Evolutionary Computation
   software.

doc/QuickStartGuides/0-Overview.rst

@@ -0,0 +1,15 @@
+Overview
+========
+
+The goal of Empirical is to simplify the development of efficient, reliable, and accessible
+scientific software.
+
+We have several quick-start guides for different portions of the code.
+
+Getting started:
+- Using specific header files is simple, just :code:`#include` them into your own project.
+We recommend adding your :code:`Empirical/source/` folder to the include directories for your C++ compiler (usually with the :code:`-I` option).
+- To use the web features in Empirical, you must first install the emscripten compiler, which can be slightly more complicated.
+* Our `Hello World Guide`_ will help you get compiling with Empirical, natively and for web.
+
+.. _`Hello World Guide`: 1-HelloWorld.html

doc/QuickStartGuides/1-HelloWorld.rst

@@ -0,0 +1,211 @@
+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 :code:`gcc` and :code:`clang`.
+From this point onwards, we assume that you're working with :code:`gcc`.
+Unless you really know what you're doing, you'll want to have :code:`gcc` installed.
+The good news is: you might already!
+
+Bring up a terminal and try entering:
+
+.. code-block:: bash
+
+  which gcc
+
+If :code:`which` spits out a path, then you have :code:`gcc` installed!
+If :code:`which` says "not found," you'll need to go ahead and install :code:`gcc`.
+For Linux users, your package manager (e.g., :code:`yum`, :code:`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.
+
+.. code-block:: bash
+
+  git clone https://github.com/devosoft/Empirical
+  cd Empirical/examples/ProjectTemplate
+
+Let's take a look at what we want to compile.
+
+:code:`source/native/project_name.cc`:
+
+.. code-block:: c++
+
+  // This is the main function for the NATIVE version of this project.
+
+  #include <iostream>
+
+  #include "base/vector.h"
+  #include "config/command_line.h"
+
+  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.
+
+.. code-block:: c++
+
+  #include "base/vector.h"
+  #include "config/command_line.h"
+
+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!
+
+.. code-block:: bash
+
+  make
+
+If you :code:`ls`, you should now see the executable :code:`project_name` has been created.
+Let's run!
+
+.. code-block:: bash
+
+  ./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.
+
+.. _emscripten LLVM-to-Web Compiler: https://emscripten.org
+
+We aim for Empirical to track the current release of emscripten.
+However, as of February 2019, we've fallen a bit behind due to some breaking changes in recent emscripten releases.
+(See, e.g., `Empirical Issue #197`_).
+While we're working on bringing Empirical up-to-date with the latest emscripten, you'll need to work with emscripten version :code:`v1.37.1` in order to compile Empirical's web tools.
+
+.. _Empirical Issue #197: https://github.com/devosoft/Empirical/issues/197
+
+Here's how to get that taken care of.
+
+.. code-block:: bash
+
+  git clone https://github.com/emscripten-core/emsdk.git
+  cd emsdk
+  ./emsdk install emscpripten v1.37.1
+  ./emsdk activate emscpripten v1.37.1
+  ./emsdk install clang-e1.37.1-64bit
+  ./emsdk activate clang-e1.37.1-64bit
+
+When you want to use the emscripten compiler, you'll want to hop over to the :code:`emsdk` directory and run
+
+.. code-block:: bash
+
+  source ./emsdk_env.sh
+
+in order to load emscripten's odds and ends into your :code:`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 :code:`Empirical/examples/ProjectTemplate` and you have loaded up emscripten (e.g., :code:`source source ./emsdk_env.sh`), compiling for web is a snap!
+
+Let's take a look at what we want to compile first, though.
+
+:code:`source/web/project_name-web.cc`:
+
+.. code-block:: c++
+
+  //  This file is part of Project Name
+  //  Copyright (C) Michigan State University, 2017.
+  //  Released under the MIT Software license; see doc/LICENSE
+
+  #include "web/web.h"
+
+  namespace UI = emp::web;
+
+  UI::Document doc("emp_base");
+
+  int main()
+  {
+    doc << "<h1>Hello, world!</h1>";
+  }
+
+The line
+
+.. code-block:: c++
+
+  #include "web/web.h"
+
+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
+
+.. code-block:: c++
+
+  UI::Document doc("emp_base");
+
+creates a persistent :code:`UI::Document` object (e.g., outside the scope of the :code:`main` function) that hooks into the :code:`"emp_base"` div in :code:`web/project_name.html`.
+
+Then, in :code:`main`, we write our message to the :code:`"emp_base"` div (wrapped in some html markup formatting... e.g., :code:`<h1>` and :code:`</h1>`).
+
+You can find a more comprehensive explanation of the contents of this `.cpp` file in our `Quick Start Guide for Web Tools`_.
+
+.. _`Quick Start Guide for Web Tools`: 3-WebTools.html
+
+Let's compile
+
+.. code-block:: bash
+
+  make web
+
+We should now have :code:`web/project_name.js` and :code:`web/project_name.js.mem` ready to go.
+You can verify this by entering :code:`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
+
+.. code-block:: bash
+
+  python3 -m http.server
+
+at your command line.
+If it starts up, then great!
+Just leave it running for now.
+
+If you don't have :code:`python3` 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`_.
+
+.. _`http://localhost:8000/web/project_name.html`: 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 :code:`<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_).
+
+.. _here: 4-UsingProjectTemplate.html

doc/QuickStartGuides/2-BaseTools.rst

@@ -0,0 +1,67 @@
+Base Tools
+==========
+
+A handful of tools are available in the source/base/ folder in Empirical.  These mimic basic
+functionality available in C++ or the standard library, but provide extra protection against
+common memory use errors and additional information to the developer.
+
+base/assert.h
+---------------------
+
+This file adds an :code:`emp_assert` macro that can handle all of the same functionality as the
+standard library assert, but with additional features.  Specifically, additional arguments
+may be added that are printed when the assert is triggered.  For example, the line
+
+.. code-block:: C++
+
+  emp_assert(i < 10, i);
+
+if triggered, would print something to the effect of
+
+.. code-block:: bash
+
+  Assert Error (In assert.cc line 6): i < 10
+  i: [1844674]
+  Abort
+
+Indicating that not only was :code:`i >= 10`, but its current value is 1844674.
+
+If compiled as part of a web app (with emscripten) :code:`emp_assert`: will automatically use the
+JavaScript Alert function to indicate any assert failures.  Asserts are all disabled (fully
+removed from compiled code) if compiled using the :code:`NDEBUG` option (for most compilers, this
+deactivation is accomplished by using the :code:`-DNDEBUG` flag at compile time.)
+
+
+base/array.h and base/vector.h
+----------------------------------
+
+These files setup the :code:`emp::array<...>` and :code:`emp::vector<...>` template objects, which behave
+almost identically to :code:`std::array<...>` and :code:`std::vector<...>`, respectively.  The one difference
+is that they do bounds checking when they are indexed into or specific size matters.  As with
+asserts, these additional bounds checks are removed when compiled with the :code:`NDEBUG` option.
+
+
+base/Ptr.h
+-------------
+
+The :code:`emp::Ptr<...>` template provides an alternate method of building pointers, but with the
+ability to turn on additional debugging facilities; unlike assert, array, and vector, no
+debugging is performed by default due to substantial run-time costs.  For example declaring a
+variable as :code:`emp::Ptr<int>` is the same as declaring it :code:`int *`.
+
+If the :code:`EMP_TRACK_MEM` option is set (:code:`-DEMP_TRACK_MEM` compiler flag) then all pointer usage is
+tracked and many simple memory errors will be identified during execution, such as using or
+deleting an unallocated pointer.
+
+Most usage of the :code:`Ptr` class is identical to raw pointers, including all operator.
+Differences include:
+
+* Rather than using :code:`new TYPE` to allocate a new pointer, use :code:`emp::NewPtr<TYPE>`
+* If allocating an array, use :code`:emp::NewArrayPtr<TYPE>(SIZE)`
+* To delete use the :code:`.Delete()` or :code:`.DeleteArray()` member function (not :code:`delete` or :code:`delete[]`).
+* To cast one :code:`Ptr` type to another, use the :code:`.Cast<TYPE>` member function.
+* To dynamic cast (double-checking types and returning :code:`nullptr` on failure), use :code:`.DynamicCast<TYPE>`
+
+
+To convert a :code:`Ptr`-allocated pointer to the raw form, use the :code:`Raw()` member function.  Make sure
+that any pointer allocated as a :code:`Ptr` type is also freed as a :code:`Ptr` type.