From bec5cd5e5c12a38168e0a117adccccd6e3407e9f Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Sat, 14 Mar 2015 14:11:07 +0100 Subject: [PATCH] docs(README): add build instructions These should help people to get started on their own. Fixes #9 --- README.md | 57 +++++++++++++++++++ etc/api/freebase/v1-sandbox/freebase-api.json | 4 +- etc/api/freebase/v1/freebase-api.json | 4 +- etc/api/freebase/v1sandbox/freebase-api.json | 4 +- 4 files changed, 63 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2bd3a8516e..96eb8c8626 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,63 @@ Click the image below to see the playlist with all project related content: [![thumb][playlist-thumb]][playlist] +# Build Instructions + +## Prerequisites + +To generate the APIs yourself, you will need to meet the following prerequisites: + +* **make** + * Make is used to automate and efficiently call all involved programs +* **python** + * As [*mako*][mako] is a python program, you will need python installed on your system to run it. Some other programs we call depend on python being present as well. +* **an internet connection and wget** + * Make will download all other prerequisites automatically into hidden directories within this repository, which requires it to make some downloads via wget. + +## Using Make + +The makefile is written to be self-documenting. Just calling `make` will yield a list of all valid targets. + +```bash +➜ google-apis-rs git:(master) make +using template engine: '.pyenv/bin/python etc/bin/mako-render' + +Targets +docs - cargo-doc on all APIs, assemble them together and generate index +github-pages - invoke ghp-import on all documentation +apis - make all APIs +cargo - run cargo on all APIs, use ARGS="args ..." to specify cargo arguments +regen-apis - clear out all generated apis, and regenerate them +clean-apis - delete all generated APIs +help-api - show all api targets to build individually +help - print this help +license - regenerate the main license file +update-json - rediscover API schema json files and update api-list.yaml with latest versions +api-deps - generate a file to tell make what API file dependencies will be +make: Nothing to be done for `help'. +``` + +You can easily build the documentation index using `make docs` and individual API documentation using `make -doc`. Run doctests on all apis with `make cargo ARGS=test` or on individual ones using `make -cargo ARGS=test`. To see which API targets exist, run `make help-api`. + +## Make and parallel job execution + +In theory, you can run make with `-j4` to process 4 jobs in parallel. However, please note that `cargo` may be run for some jobs and do a full build, which could cause it to fail as it will be updating it's index. The latter isn't working for multiple cargo processes at once as the index is a shared resource. + +Nonetheless, once you have built all dependencies for all APIs once, you can safely run cargo in parallel, as it will not update it's index again. + +In other words: The first time, you run `make docs` and `make cargo ARGS=test`, you shouldn't run things in parallel. The second time, you are free to parallelize at will. + +## Adding new APIs and updating API schemas + +The list of available APIs to generate is based on a query of the [Google discovery API][api-discovery], and then baked into a make-compatible dependency file. That will represents a cache, and the only way to enforce a full update is to delete it and run make again. + +For example, to update all json files and possibly retrieve new API schemas, do as follows: + +```bash +# -j8 will allow 8 parallel schema downloads +rm -f .api.deps && make update-json -j8 +``` + # License The license of everything not explicitly under a different license are licensed as specified in `LICENSE.md`. diff --git a/etc/api/freebase/v1-sandbox/freebase-api.json b/etc/api/freebase/v1-sandbox/freebase-api.json index fd98597a38..2894303506 100644 --- a/etc/api/freebase/v1-sandbox/freebase-api.json +++ b/etc/api/freebase/v1-sandbox/freebase-api.json @@ -1,11 +1,11 @@ { "kind": "discovery#restDescription", - "etag": "\"ye6orv2F-1npMW3u9suM3a7C5Bo/FwvhaMOD6SZYT0Ouc9Sk-CI5lgY\"", + "etag": "\"ye6orv2F-1npMW3u9suM3a7C5Bo/9O-B4rHzgH3tXg2WDx70ZMEZZks\"", "discoveryVersion": "v1", "id": "freebase:v1-sandbox", "name": "freebase", "version": "v1-sandbox", - "revision": "20141210", + "revision": "20150313", "title": "Freebase Search", "description": "Find Freebase entities using textual queries and other constraints.", "ownerDomain": "google.com", diff --git a/etc/api/freebase/v1/freebase-api.json b/etc/api/freebase/v1/freebase-api.json index ef981cc54a..b71ea01d66 100644 --- a/etc/api/freebase/v1/freebase-api.json +++ b/etc/api/freebase/v1/freebase-api.json @@ -1,11 +1,11 @@ { "kind": "discovery#restDescription", - "etag": "\"ye6orv2F-1npMW3u9suM3a7C5Bo/b42JL4j5Mj0i9yGv-ODgLLktQPQ\"", + "etag": "\"ye6orv2F-1npMW3u9suM3a7C5Bo/U2INTp3yyIwHUMVfOIvpHbSCkZ8\"", "discoveryVersion": "v1", "id": "freebase:v1", "name": "freebase", "version": "v1", - "revision": "20141210", + "revision": "20150313", "title": "Freebase Search", "description": "Find Freebase entities using textual queries and other constraints.", "ownerDomain": "google.com", diff --git a/etc/api/freebase/v1sandbox/freebase-api.json b/etc/api/freebase/v1sandbox/freebase-api.json index 6ee89c950d..7533732657 100644 --- a/etc/api/freebase/v1sandbox/freebase-api.json +++ b/etc/api/freebase/v1sandbox/freebase-api.json @@ -1,11 +1,11 @@ { "kind": "discovery#restDescription", - "etag": "\"ye6orv2F-1npMW3u9suM3a7C5Bo/9nHTeVvQd2cjR7dq4JoIFQ2AZMU\"", + "etag": "\"ye6orv2F-1npMW3u9suM3a7C5Bo/J5XC4sdTNlYhA8Dv4RLZtqsJp5o\"", "discoveryVersion": "v1", "id": "freebase:v1sandbox", "name": "freebase", "version": "v1sandbox", - "revision": "20141210", + "revision": "20150313", "title": "Freebase Search", "description": "Find Freebase entities using textual queries and other constraints.", "ownerDomain": "google.com",