From cbc376ddd6f9fa2ad546478f5a655c0dd1322543 Mon Sep 17 00:00:00 2001 From: Leonardo Ayala Date: Fri, 12 Apr 2024 11:06:25 +0200 Subject: [PATCH] Updated README and dependencies on documentation --- README.md | 220 ++++++++++++++++----------------- doc/source/getting_started.rst | 2 +- 2 files changed, 109 insertions(+), 113 deletions(-) diff --git a/README.md b/README.md index a23728d..349cf8f 100644 --- a/README.md +++ b/README.md @@ -1,121 +1,117 @@ -The susicam library is only supported in Linux systems, more support is provided for Ubuntu. +The susicam library is only supported in Linux systems, although all dependencies are also available in Windows systems, +compilation in such systems has not been properly tested. -NOTE: You will need `CUDA` library and drivers installed in your computer in order to use susicam. +# Building susicam from source +This software can be built following the instructions provided in out [Getting Started guide.](https://imsy.pages.dkfz.de/issi/susicam/getting_started.html) -## Build susicam from source +# FAQ +If you are having issues, make sure to check the [FAQ section](https://imsy.pages.dkfz.de/issi/susicam/faq.html) of our documentation. -To build susicam you only need to install the dependencies and run the build as in the following commands. -```bash -sudo apt install libopencv-dev libboost-all-dev libgtest-dev gcovr libqt6svg6-dev qt6-base-dev cmake g++ wget -``` - -You will also have to install the xiAPI package provided my XIMEA - -```bash -wget --progress=bar:force:noscroll https://www.ximea.com/downloads/recent/XIMEA_Linux_SP.tgz -tar xzf XIMEA_Linux_SP.tgz -cd package -sudo ./install -``` - -Finally, from the home directory of `susicam` do the following. Notice that the specified paths have been tested in -`Ubuntu 22.04`. If your distribution is different, the specific paths might differ. - -```bash -mkdir build -cd build -cmake -D OpenCV_DIR=/usr/include/opencv4/opencv2 -D Ximea_Include_Dir=/opt/XIMEA/include -D Ximea_Lib=/usr/lib/libm3api.so.2.0.0 .. -make all -j -ctest # to check that all tests pass -``` - -# Increase USB buffer limit -After building `susicam`, you have to increase the buffer size for the data transfer via USB. This can be done every -time you start your computer by running the following command. - -```bash -sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb >/dev/null <<<0 -``` - -Alternatively, you can create a daemon service that would start automatically every time you start your computer. -```bash -sudo nano /etc/systemd/system/usb-buffer-size.service -``` -You will need to paste the following content in the file opened above -```bash -[Unit] -Description=Increase USB Buffer Size - -[Service] -ExecStart=/bin/bash -c 'sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb >/dev/null <<<0' -Type=oneshot -RemainAfterExit=yes - -[Install] -WantedBy=multi-user.target -``` -Then you have to enable and start the service -```bash -sudo systemctl enable usb-buffer-size.service -sudo systemctl start usb-buffer-size.service -service usb-buffer-size status -``` -You should see that the service is marked as `active`. - -# Launching the application -You can start the application by doing `./SUSICAM` from the terminal. Alternatively you can create an application -launcher by copying the `susicam.deskptop` and `icon.png` files to `~/.local/share/applications`. After copying these -files, you will have to modify the paths inside `~/.local/share/applications/susicam.deskptop` to represent the -full path to the executable and the `icon.png` file: - -```bash -Exec=/home///SUSICAM -Icon=/home//.local/share/applications/icon.png -``` - -## Build docker image -Running a Qt application inside docker is not straight forward. Building the docker image can serve to test your -developed code to make sure that it will work in other systems, however running the application inside docker is still -under development. - -```bash -docker compose --verbose build --progress plain -docker run -it --privileged -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --gpus all --device /dev/bus/usb/ -e QT_X11_NO_MITSHM=1 -e QT_GRAPHICSSYSTEM="native" susicam -``` --- -## FAQ - -1. Errors related to libtiff conflicts: -`Libopencv_imgcodes.so.4.2.0: undefined reference to 'TIFFReadRGBAStripe@IBTIFF_4.0'` -`no rule to make target '../anaconda3/lib/libhdf5_cpp.sp', needed by 'libsusiCamLib.so'` - -**Solution:** +## **Developer guidelines** :computer: +
+ +These guidelines are meant to help you develop code for this package: documentation, unittesting, bug fixes, features, releases, etc. (click to expand) + + + +### General rules +1. Binary files can NOT be added to the repository, ideally you should develop your code in `.cpp, .h` files. + Example of files that should NOT be added to the repository: `.png`, `.tif`, `.npy`, `.pkl`, `.dat`, `.html` + If you have doubts about the files you are committing, you can always ask for help. +2. Branch naming follows `git flow` conventions, you can find a cheatsheet with the most common commands here + [GitFlow](https://danielkummer.github.io/git-flow-cheatsheet/). + In order to initialize git flow in your environment you need to run: + + `git flow init -d` + + Before starting your `feature`, `hotfix`, etc. + you need to create a task in the [SUSICAM work board](https://git.dkfz.de/imsy/issi/susicam/-/issues). + After creating the task you will see a number like this `18` in the title of the task. You should use this for + naming your branch. For example: + + `git flow feature start 18-my_branch_name` + + This will create a branch with the name `feature/18-my_branch_name`, notice that `git flow` prepends `feature` to + the branch name automatically. More details on how to finish the branch can be found in the section [contributing a feature](#contributing-a-featurebug-fix) +3. You need to have implemented tests for your code before merging into develop, we use GoogleTests for that. You also need to have written documentation for your implementations. + +### Documentation :book: + +Ideally all your code should be documented, the markup used for the documentation is [**Doxygen-style**](https://www.doxygen.nl/manual/docblocks.html). +You should stick to it. The documentation can be built by doing the following. ```bash -conda uninstall libtiff +cd doc +sudo apt install -y doxygen graphviz +pip install -U sphinx furo breathe +doxygen Doxyfile +make html SPHINXOPTS="-j4" ``` - -2. Error: Linking error of `libuuid` -```bash -can not link -luuid -``` -You most likely are missing the `uuid-dev` package, to fix this you cna install it via: -```bash -sudo apt install uuid-dev -``` - -3. Error: Number of XIMAE devices found:0 - -```bash -number of ximea devices found: 0 -xiAPI: ---- xiOpenDevice API:V4.25.03.00 started ---- -xiAPI: EAL_DeviceEnumerator::OpenDevice - no camera with index 0 is available -xiAPI: EAL_DeviceEnumerator::OpenDevice - can not find device by ID 00000000 -xiAPI: xiAPI error: Expected XI_OK in:../API/xiFAPI/interfaces/01_top/xifapi_Top.cpp xiOpenDevice/Line:86 -``` -This is due to the fact that your user is not a member of the correct group `plugdev`. To fix this issue, run the following command and restart your PC. -```bash -sudo usermod -aG plugdev $(whoami) -``` \ No newline at end of file +After that, you should see a build directory where the html code is written to. + + +### Unittesting :test_tube: + +As mentioned before, your code should ideally be tested thoroughly. For this we use `unittests`. You can find examples of +it in the already created unittests in our repository. + +### Contributing a feature/bug fix :bug: +If you have doubts on how to finish your feature branch, you can always ask for help +1. Create issue on the [SUSICAM work board](https://git.dkfz.de/imsy/issi/susicam/-/issues), if a task does not exist yet. +2. Assign the task to you. +3. Create the `feature` branch: `git flow feature start `. + >`` has to match the following pattern: `-` +4. Update `feature` branch: `git checkout && git merge develop` +5. Run tests in `feature` branch +6. Create a merge request for your feature in gitlab, select `develop` and the destination branch and assign reviewers +7. The branch will be reviewed and automatically merged if there are no requested changes + +### Contributing a hotfix :fire: +The version tag has to match the following pattern: `v..` with `x=major, y=minor, z=patch` version number + +1. Create a task on the [SUSICAM work board](https://git.dkfz.de/imsy/issi/susicam/-/issues), if a task does not exist yet. +2. Set the task priority to high, if not done yet. +3. Assign the task to you. +4. Create the `hotfix` branch: `git flow hotfix start `. + > `` has to match the following pattern: `-` +5. Commit your hot fixes. +6. Bump the version number in the last commit. Increment the patch number of the latest version tag by one. Following files have to be touched: + * `doc/conf.py` +7. Finish the `hotfix` by specifying the version tag and the message: `git flow hotfix finish - -T -m "Release of susi package"` +8. The `hotfix` branch has been merged into `main` and `develop`. The `hotfix` branch has been deleted locally and remotely. You are now on `develop` branch, which has to be pushed. +9. Switch to `main` branch and also push it. +10. Also push the version tag: `git push origin `, or alternatively `git push --tags` +11. Change status of the task to `resolved`. + +## Preparing a release :package: +The version tag has to match the following pattern: `v..` with `x=major, y=minor, z=patch` version number + +1. Releases are tracked via [milestones](https://git.dkfz.de/imsy/issi/susicam/-/milestones). +2. Make sure that all tasks relevant for the corresponding milestone have been resolved. +3. Create a `release` branch: `git flow release start `. The version tag is the title of the milestone. +4. Perform testing on the `release` branch. + * run tests + * Fix issues on the `release` branch + * Repeat testing procedure until no errors occur +5. Update release number. Following files have to be touched: + * `doc/conf.py` +6. Finish a release: `git flow release finish -T -m "Release of susicam package"` +7. Push `develop` branch and `master` branch. +8. Push tags with `git push origin `, or alternatively `git push --tags` +9. Change status of all release-relevant tasks to resolved (if not done already). + +### Finished or deprecated branches :older_adult: + +Branches that are no longer in use or that have been merged into develop should be deleted, except persistent branches such as `documentation`. +If you followed the guidelines for finishing a feature, your feature branch should have been deleted automatically. +If you merged into develop but your branch is still there, you can delete it manually by doing + +>Make sure that your code is already in develop (before delete branches) by going to [susicam](https://git.dkfz.de/imsy/issi/susicam) and checking the develop branch + +`git branch -d ` +`git push origin --delete ` + +
diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index 06d0e10..b69c10e 100644 --- a/doc/source/getting_started.rst +++ b/doc/source/getting_started.rst @@ -14,7 +14,7 @@ build as in the following commands. .. code:: bash - sudo apt install libopencv-dev libboost-all-dev libgtest-dev gcovr qt6-base-dev cmake g++ wget + sudo apt install libmsgpack-dev qt6-base-dev libqt6svg6-dev libgtest-dev gcovr libopencv-dev --no-install-recommends libboost-all-dev You will also have to install the xiAPI package provided my XIMEA