<commit_before># Build Instructions

This page guides readers through building the components of 
[Seattle Testbed](https://github.com/SeattleTestbed).  The Seattle Testbed 
is comprised of a dozen, or so, interdependent sub-components that may be 
individually built, run, and tested.  Specifically, this instructional guide 
covers the `initialize.py` and `build.py` scripts that are utilized by all 
of the Seattle Testbed components; these two build scripts may be used to 
fetch each component's dependencies, and to build the component and its unit 
tests.  There are sections explaining how to build components; how to build 
and run a component's unit tests; the different use cases for the build 
scripts; how contributors will typically develop and contribute source code 
while using the build scripts; and how the build scripts themselves work. 
The guide begins by discussing the software prerequisites of the 
Seattle Testbed.

-----

## Prerequisites
Before you begin, make sure that you have the following pieces of software 
on your computer:
* [Python 2.7](https://www.python.org/downloads/).
* [Git 1.7](http://www.git-scm.com/download) (or later)

Many operating systems (such as Linux and Mac OS X) ship with these installed. 
On Windows, you will usually need to install Python and Git.

*Note: Please double-check your Python version! We don't support Python 3 
at the moment.*


## Building components
This section describes how to build components from their source repositories 
on [GitHub](https://github.com/SeattleTestbed), using the command line. We'll 
use a Unix-like system throughout our examples. Windows users should use 
Windows PowerShell or Command Prompt.

Currently, components that have been set up to be buildable and runnable
are `seash`, `repy_v2`, `overlord`, and `experimentmanager`. The other 
components can be built for unit test mode (see below).


*Note:* Overlord and Experiment Manager are currently being ported to 
RepyV2 and do not fully work at the moment.


1. Clone the repository that you want to build from [
SeattleTestbed](https://github.com/SeattleTestbed).

For example, if you are building [wiki:SeattleShell seash], do: 
```sh
$ git clone https://github.com/SeattleTestbed/seash
```
If you usually use `SSH` instead of `https` to clone your git repos, you can do:
```sh
$ git clone <EMAIL>@github.com:SeattleTestbed/seash.git
```
Of course, you will want to replace `seash` with the repository name you 
are interested in.


2. This yields a folder named like the repository you cloned. Inside of 
it, there is a `scripts/` folder which in turn contains a script called 
`initialize.py` to fetch the dependencies of this component. Continuing 
with our example `seash`:

```sh
$ cd seash/scripts
$ python initialize.py
```
`initialize.py` Git-clones the dependent repositories into `DEPENDENCIES` 
directory which will be created as a sub-directory inside your main 
repository. It takes its instructions from `config_initialize.txt` to 
fetch the dependencies.

3. To build a runnable component from the source dependencies, run the 
`scripts/build.py` script. You may supply it an optional target folder for 
the build (which must be created first):
```sh
$ mkdir TARGET_FOLDER
$ python build.py TARGET_FOLDER
```
If you don't setup a target directory, `build.py` will itself create a 
target folder named `RUNNABLE` which will be a sub-directory inside the 
component's main repository, e.g. `seash/RUNNABLE`.

`build.py` will copy all the files necessary to build the particular Seattle 
Component into the target directory. It will indirectly call 
`../DEPENDENCIES/common/build_component.py` and make use of `config_build.txt` 
in order to fetch the list of files and directories to copy to target.


*Done!* Your target folder now contains a runnable version of the component! 


## Building and Running Unit Tests
When making changes to the code (or build scripts!) you will want to ensure 
that the change does not have side effects or breaks functionality that had 
been working before. In order to ensure this, most components are *testable* 
and come with a set of *unit tests*. These components have a `tests` or 
`test` directory within their repository.

The steps of the previous section intrinsically downloaded the required 
unit test files. You just need to run the build script again to create a 
testable build. Use the `-t` command line option to indicate you want 
the test files to be included. Again, specifying a target directory is optional!
```sh
$ mkdir TEST_TARGET_DIR
$ cd COMPONENT/scripts<commit_msg>Make RepyV2 the example in BuildInstructions.md<commit_after># Build Instructions

This page guides readers through building the components of 
[Seattle Testbed](https://github.com/SeattleTestbed).  The Seattle Testbed 
is comprised of a dozen, or so, interdependent sub-components that may be 
individually built, run, and tested.  Specifically, this instructional guide 
covers the `initialize.py` and `build.py` scripts that are utilized by all 
of the Seattle Testbed components; these two build scripts may be used to 
fetch each component's dependencies, and to build the component and its unit 
tests.  There are sections explaining how to build components; how to build 
and run a component's unit tests; the different use cases for the build 
scripts; how contributors will typically develop and contribute source code 
while using the build scripts; and how the build scripts themselves work. 
The guide begins by discussing the software prerequisites of the 
Seattle Testbed.

-----

## Prerequisites
Before you begin, make sure that you have the following pieces of software 
on your computer:
* [Python 2.7](https://www.python.org/downloads/).
* [Git 1.7](http://www.git-scm.com/download) (or later)

Many operating systems (such as Linux and Mac OS X) ship with these installed. 
On Windows, you will usually need to install Python and Git.

*Note: Please double-check your Python version! We don't support Python 3 
at the moment.*


## Building RepyV2
This section describes how to build RepyV2, SeattleTestbed's sandbox,
from its source repository on [GitHub](https://github.com/SeattleTestbed),
using the command line.
We'll use a Unix-like system throughout our examples. Windows users
should use Windows PowerShell or Command Prompt.

*Note: These build instructions apply similarly to all other SeattleTestbed
components.*


1. Clone the RepyV2 repository from [SeattleTestbed's GitHub](https://github.com/SeattleTestbed).

```sh
$ git clone https://github.com/SeattleTestbed/repy_v2
```
If you usually use `SSH` instead of `https` to clone your git repos, you can do:
```sh
$ git clone <EMAIL>:SeattleTestbed/repy_v2.git
```

(If you want to clone a different repository, replace `repy_v2` with
the appropriate repository name.)


2. This yields a folder named like the repository you cloned. Inside of 
it, there is a `scripts/` folder which in turn contains a script called 
`initialize.py` to fetch the dependencies of this component. Continuing 
with `repy_v2` for this concrete walkthrough:

```sh
$ cd repy_v2/scripts
$ python initialize.py
```

`initialize.py` Git-clones the dependent repositories into `DEPENDENCIES` 
directory which will be created as a sub-directory inside your main 
repository. It takes its instructions from `config_initialize.txt` to 
fetch the dependencies.

3. To build a runnable component from the source dependencies, run the 
`scripts/build.py` script. You may supply it an optional target folder for 
the build (which must be created first). Name this folder as you like.
```sh
$ mkdir TARGET_FOLDER
$ python build.py TARGET_FOLDER
```

If you don't setup a target directory, `build.py` will itself create a 
target folder named `RUNNABLE` which will be a sub-directory inside the 
component's main repository, e.g. `repy_v2/RUNNABLE`.

`build.py` will copy all the files necessary to build the particular Seattle 
Component into the target directory. It will indirectly call 
`../DEPENDENCIES/common/build_component.py` and make use of `config_build.txt` 
in order to fetch the list of files and directories to copy to target.


*Done!* Your target folder now contains a runnable version of the
RepyV2 sandbox (or other component you chose)!


## Building and Running Unit Tests
When making changes to the code (or build scripts!) you will want to ensure 
that the change does not have side effects or breaks functionality that had 
been working before. In order to ensure this, most components are *testable* 
and come with a set of *unit tests*. These components have a `tests` or 
`test` directory within their repository.

The steps of the previous section intrinsically downloaded the required 
unit test files. You just need to run the build script again to create a 
testable build. Use the `-t` command line option to indicate you want 
the test files to be included. Again, specifying a target directory is optional!
```sh
$ mkdir TEST_TARGET_DIR
$ cd COMPONENT/scripts
{'fraction_non_alphanumeric': 0.06481583895586772, 'fraction_numerical': 0.00320760977767946, 'mean_word_length': 4.510054844606947, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 10, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1189717', 'n_tokens_mistral': 2484, 'n_tokens_neox': 2391, 'n_words': 1265}