From 5b841655515244aa9c76d744613e1b10c865dc71 Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Thu, 5 Apr 2018 09:01:15 +0200 Subject: [PATCH] Document how to add a new project Signed-off-by: Michael Opdenacker --- README.md | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 91 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 255aa0b..cd9d5c7 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ duplicating work and data. It has a straightforward data structure Requirements ------------ -* >= Python 3.5 +* Python >= 3.5 * The Jinja2 and Pygments Python libraries * Berkeley DB (and its Python binding) * Exuberant Ctags @@ -88,9 +88,7 @@ directory with a specific structure: * repo It will then generate the other two variables upon calling the query -command. For now, three projects are hard-coded into the shell script -(to handle version grouping and display): Linux, U-Boot, Busybox, -Musl and Zephyr. +command. Here is an example configuration for Apache: @@ -115,4 +113,92 @@ Here is an example configuration for Apache: Don't forget to enable cgi and rewrite support with `a2enmod cgi rewrite`. -Note: this documentation applies to version 0.2 of Elixir. +Supporting a new project +------------------------ + +Elixir has a very simple modular architecture that allows to support +new source code projects by just adding a new file to the Elixir sources. + +Elixir's assumptions: + +* Project sources have to be available in a git repository +* All project releases are associated to a given git tag. Elixir + only considers such tags. + +First make an installation of Elixir by following the above instructions. +See the `projects` subdirectory for projects that are already supported. + +Once Elixir works for at least one project, it's time to clone the git +repository for the project you want to support: + +> cd /srv/git +> git clone --bare https://github.com/zephyrproject-rtos/zephyr + +Now, in your `LXR_PROJ_DIR` directory, create a new directory for the +new project: + + cd $LXR_PROJ_DIR + mkdir -p zephyr/data + ln -s /srv/git/zephyr.git repo + export LXR_DATA_DIR=$LXR_PROJ_DIR/data + export LXR_REPO_DIR=$LXR_PROJ_DIR/repo + +Now, go back to the Elixir sources and test that tags are correctly +extracted: + +> ./script.sh list-tags + +Depending on how you want to show the available versions on the Elixir pages, +you may have to apply substitutions to each tag string, for example to add +a `v` prefix if missing, for consistency with how other project versions are +shown. You may also decide to ignore specific tags. All this can be done +by redefining the default `list_tags()` function in a new `project/.sh` +file. Here's an example (`projects/zephyr.sh` file): + + list_tags() + { + echo "$tags" | + grep -v '^zephyr-v' + } + +Note that `` **must** match the name of the directory that +you created under `LXR_PROJ_DIR`. + +The next step is to make sure that versions are classified as you wish +in the version menu. This classification work is done through the +`list_tags_h()` function which generates the output of the `./scripts.sh list-tags -h` +command. Here's what you get for the Linux project: + + v4 v4.16 v4.16 + v4 v4.16 v4.16-rc7 + v4 v4.16 v4.16-rc6 + v4 v4.16 v4.16-rc5 + v4 v4.16 v4.16-rc4 + v4 v4.16 v4.16-rc3 + v4 v4.16 v4.16-rc2 + v4 v4.16 v4.16-rc1 + ... + +The first column is the top level menu entry for versions. +The second one is the next level menu entry, and +the third one is the actual version that can be selected by +the menu. + +If the default behavior is not what you want, you will have +to customize the `list_tags_h` function. + +You should also make sure that Elixir properly identifies +the most recent versions: + +> ./script.sh get-latest + +If needed, customize the `get_latest()` function. + +You are now ready to generate Elixir's database for your +new project: + +> ./update.py + +You can then check that Elixir works through your http server. + +Note: this documentation applies to version 0.3 of Elixir.