xref: /OpenGrok/tools/README.md (revision a840d4e0a51644f01cec6d36d31156074cc8ec8d)
1
2# OpenGrok tools
3
4Set of scripts to facilitate project synchronization and mirroring
5
6The scripts require Python 3 and they rely on a binary/symlink `python3` to be
7present that points to the latest Python 3.x version present on the system.
8
9Currently it is assumed that Python 3.6 and greater is used.
10
11See https://github.com/oracle/opengrok/wiki/Repository-synchronization
12for more details.
13
14# Content
15
16This is a list of the binaries in this package.
17
18```text
19opengrok-config-merge
20opengrok-deploy
21opengrok-groups
22opengrok
23opengrok-indexer
24opengrok-java
25opengrok-mirror
26opengrok-projadm
27opengrok-reindex-project
28opengrok-sync
29```
30
31# Development
32
33## Environment
34
35Prepare a virtual environment
36
37```bash
38python3 -m venv env
39. env/bin/activate
40```
41
42## Developing
43
44When you start developing, install the package in a development mode.
45
46```bash
47python setup.py develop
48```
49
50This installs the package however keeping the links directly to your source,
51so you can edit the files and see the immediate results.
52
53Start developing, making changes in files. Test your changes with calling the entry points.
54
55```bash
56export PYTHONPATH=`pwd`/src/main/python:$PYTHONPATH
57opengrok-groups
58opengrok-sync
59```
60
61It is necessary to set the python path as the python interpreter is not able to find the packages
62in our provided structure on its own.
63
64Also you call the opengrok tools scripts by the entry points then (`opengrok-groups`, ...).
65Calling directly the python script `groups.py` would lead to error related to relative imports.
66
67Note that on macOS, you will need to install libgit2 library for the tests
68to pass.
69
70## Installation
71
72Test installing your package into the local environment
73
74```bash
75python setup.py install
76# now you can try console scripts
77opengrok-groups
78opengrok-sync
79```
80
81or make a distribution tarball.
82
83```bash
84python setup.py sdist
85ls -l dist/
86```
87
88### Installation on the target system
89
90Use the distribution tarball and run `pip`.
91
92```bash
93python3 -m pip install opengrok-tools.tar.gz
94```
95
96This will download all dependencies and install the package to your local python3 modules.
97You can use console scripts to run the package binaries.
98
99#### Installing to a specified directory
100
101You can also install the tools to a specified directory, we suggest you to use the python virtual environment for it.
102
103```bash
104cd /opt/opengrok
105python3 -m venv opengrok-tools
106opengrok-tools/bin/python -m pip install opengrok-tools.tar.gz
107```
108
109This will install the package and all the dependencies under the `/opt/opengrok/opengrok-tools` directory.
110You can then call the scripts with
111
112```bash
113/opt/opengrok/opengrok-tools/bin/opengrok-indexer
114/opt/opengrok/opengrok-tools/bin/opengrok-groups
115...
116```
117
118#### Uninstalling
119
120```bash
121python3 -m pip uninstall opengrok_tools
122```
123
124## Testing
125
126```bash
127python setup.py install test
128./mvnw test
129```
130
131## Cleanup
132
133Deactivate the virtual environment
134```bash
135deactivate
136# optionally
137# rm -r env
138```
139
140