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