From f4e6dfe897841ced4311c48d4b5f9dc027ed005b Mon Sep 17 00:00:00 2001 From: Jaeho Shin Date: Tue, 14 Jul 2015 15:19:15 -0700 Subject: [PATCH] Updates developer's guide document --- doc/doc/advanced/developer.md | 48 +++++++++++++++++++++++++++++----- doc/doc/basics/installation.md | 7 ++--- 2 files changed, 46 insertions(+), 9 deletions(-) diff --git a/doc/doc/advanced/developer.md b/doc/doc/advanced/developer.md index 6fb627816..b14e5fc8f 100644 --- a/doc/doc/advanced/developer.md +++ b/doc/doc/advanced/developer.md @@ -47,17 +47,20 @@ DeepDive is written in several programming languages. #### DeepDive Code Structure * `src/main/scala/` contains the main Scala code. +* `shell/` contains the scripts used by the `deepdive` command-line interface. * `util/` contains utility scripts and binaries. -* `lib/` contains libraries required by some DeepDive executables in `util/`. * `ddlib/` contains the ddlib Python library that helps users write feature extractors. -* `src/test/`, `test/`, and `test.sh` contains the test code. +* `src/test/` and `test/` contains the test code. * `doc/` contains the Markdown/Jekyll source for the DeepDive website and documentation. * `examples/` contains the DeepDive examples. +* `dist/` is the default location where the built executables and runtime data will be staged. DeepDive build is controlled by several files: * `Makefile` takes care of the overall build process. -* `build.sbt`, `sbt/` and `project/` contains the build tool and configuration for Scala. +* `sbt/`, `scala.mk`, `build.sbt`, and `project/` contains the build tool and configuration for Scala. +* `stage.sh` contains the commands that stages built code under `dist/`. +* `test/bats.mk` contains the Make recipes for running tests written in [BATS](https://github.com/sstephenson/bats) under `test/`. * `.travis.yml` enables our continuous integration builds and tests at [Travis CI](https://travis-ci.org/HazyResearch/deepdive), which are triggered every time a new commit is pushed to our GitHub repository. * `Dockerfile` defines how a new Docker image for DeepDive is generated. @@ -69,12 +72,24 @@ DeepDive source tree includes several git submodules and ports: * `mln/` contains a [Tuffy](http://i.stanford.edu/hazy/hazy/tuffy/) port. -#### Building and Testing DeepDive +#### Building and Testing DeepDive -* To install all dependencies and build what's under DeepDive's source tree, run: +* To install all dependencies, run: ```bash - make + make depends + ``` + +* To build most of what's under DeepDive's source tree and install at `~/local/`, run: + + ```bash + make # or make install + ``` + + Overriding the `PREFIX` variable allows the installation destination to be changed. For example: + + ```bash + make install PREFIX=/opt/deepdive ``` * To run all tests, from the top of the source tree, run: @@ -85,6 +100,27 @@ DeepDive source tree includes several git submodules and ports: Note that at least one of PostgreSQL, MySQL, or Greenplum database must be running to run the tests. +* To run tests selectively, use `ONLY` and `EXCEPT` Make variables for `make test`. + + For example, to run only the test with spouse example against PostgreSQL: + + ```bash + make test ONLY=test/postgresql/spouse_example.bats + ``` + + Or, to skip the tests against MySQL: + + ```bash + make test EXCEPT=test/mysql/*.bats + ``` + +* To create a tarball package from the built and staged code, run: + + ```bash + make package + ``` + + The tarball is created at `dist/deepdive.tar.gz`. * To build the DDlog compiler from source and place the jar under `util/`, run: diff --git a/doc/doc/basics/installation.md b/doc/doc/basics/installation.md index bfb1a8c8b..8d9075a8d 100644 --- a/doc/doc/basics/installation.md +++ b/doc/doc/basics/installation.md @@ -24,7 +24,7 @@ You can install DeepDive and all its dependencies with a single command. 2. Select `deepdive` or `deepdive_from_release` when asked. Choose the latter option if you simply want to install DeepDive without any of its runtime dependencies. - + ``` $ bash <(curl -fsSL deepdive.stanford.edu/install) ### DeepDive installer for Mac @@ -34,7 +34,7 @@ You can install DeepDive and all its dependencies with a single command. [...] ``` - Here are some extra detail: + Here are some more details of each options: * For installation with the `deepdive` option, All runtime dependencies are installed. Note that some steps may ask your password. * If you don't have permission to install the dependencies, you may want to use the `deepdive_from_release` option and ask the system administrator to install DeepDive's runtime dependencies with the following command. @@ -42,8 +42,9 @@ You can install DeepDive and all its dependencies with a single command. ```bash bash <(curl -fsSL deepdive.stanford.edu/install) _deepdive_runtime_deps ``` - * For installation with `deepdive_from_source` option, DeepDive source tree is cloned at `./deepdive`, and executables are installed under `~/local/bin/`. + * For installation with `deepdive_from_source` option, extra build dependencies are installed, and DeepDive source tree is cloned at `./deepdive`, then executables are installed under `~/local/bin/`. You can run tests in DeepDive's source tree to make sure everything will run fine. + See the [developer's guide](../advanced/developer.html#build-test) for more details. ```bash cd ./deepdive