From 277f10c2b8841c2c4ba58ef1f99414658cd3f6c8 Mon Sep 17 00:00:00 2001 From: Dmitry Ivanov Date: Thu, 9 Dec 2021 15:57:24 +0300 Subject: [PATCH] Update CONTRIBUTING and DEVNOTE information + Fixed several minors: gitignore, execution bit, lineendings --- .gitignore | 3 +++ CONTRIBUTING.md | 11 ++++++-- DEVNOTE.md | 49 +++++++++++++++++++++++++--------- README.md | 5 ++-- SmokeTest.md | 4 +-- docker/unpack_and_run_utbot.sh | 0 docker/utbot_docker_dev.sh | 2 +- 7 files changed, 53 insertions(+), 21 deletions(-) mode change 100644 => 100755 docker/unpack_and_run_utbot.sh diff --git a/.gitignore b/.gitignore index 259148fa1..058821a25 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,6 @@ *.exe *.out *.app + +# CLion/IDEA files +.idea \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0aed538b..033b0c7f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,6 +13,13 @@ If not - create a new one containing: * Steps to reproduce *(to be on the same page)* * Actual and expected result *(what went wrong?)* -If you already have a PR with solution - link it with the created issue +If you already have a PR with solution - link it with the created issue. -Please refer to [SmokeTest.md](SmokeTest.md) before submitting PR +##How to setup development environment? + +Please refer [Developer guide](DEVNOTE.md) to setup developer environment, build and run UTBot. + +##How to test you PR? + +Currently, not all checks are automized. It's required to do manual testing after PR. +Please perform steps from [SmokeTest.md](SmokeTest.md) before submitting PR for reviewing. diff --git a/DEVNOTE.md b/DEVNOTE.md index f34eaea84..4f676dda1 100644 --- a/DEVNOTE.md +++ b/DEVNOTE.md @@ -1,28 +1,51 @@ +#UTBot Developer Guide + ## How to build UTBotCpp from source UTBot has many dependencies, so the easiest way to build the tool from source and develop it is to use the docker container. -UTBot has a published package called [base_env](https://github.com/UnitTestBot/UTBotCpp/pkgs/container/utbotcpp%2Fbase_env). -It contains all the needed dependencies such as Git, LLVM, GRPC, GoogleTest and so on. **base_env** has multiple versions tagged with dates. -If you are developing the tool, you are most likely to need the most recent version. +UTBot has a published docker package called [base_env](https://github.com/UnitTestBot/UTBotCpp/pkgs/container/utbotcpp%2Fbase_env). +It contains all the needed dependencies such as Git, LLVM, GRPC, GoogleTest and others. **base_env** has multiple versions tagged with dates. +If you are developing the tool, you are most likely to need the most recent version from [here](https://github.com/UnitTestBot/UTBotCpp/pkgs/container/utbotcpp%2Fbase_env). +Supported and tested development configuration are Ubuntu 18.04, Ubuntu 20.04 or Windows Subsystem for Linux (+Ubuntu 18.04 / 20.04). + To build UTBot from sources: -1. Install [docker](https://docs.docker.com/engine/install/ubuntu/) -2. Run the command +1. Install docker for [Ubuntu](https://docs.docker.com/engine/install/ubuntu/) or [WSL+Ubuntu](https://docs.docker.com/desktop/windows/wsl/) +2. Install docker plugin that allows to mount host filesystem and remap owner and group: ``` docker plugin install lebokus/bindfs ``` -3. You need to do `docker login` to `ghcr.io` as described [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). -4. Run `utbot_docker_dev.sh` [script](https://github.com/UnitTestBot/UTBotCpp/blob/main/docker/utbot_docker_dev.sh). It will unpack the docker image and mount UTBot sources inside it. +3. Login into github docker registry: + ``` + docker login -u -p ghcr.io + ``` + > You can create new on [this github page](https://github.com/settings/tokens/new). Don't forget to check `read:packages` permission. + > More details are described [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). + +4. Run `docker/utbot_docker_dev.sh` [script](https://github.com/UnitTestBot/UTBotCpp/blob/main/docker/utbot_docker_dev.sh). It will unpack the docker image and mount UTBot sources inside it. UTBot binary can be built in the docker and run in it. - The script will prompt you to enter docker image tag. You can find the most recent tag [here](https://github.com/UnitTestBot/UTBotCpp/pkgs/container/utbotcpp%2Fbase_env), for example `24-11-2021`. Also it will ask about `ssh` port required to ssh into the container using `ssh utbot@host -p $port`, where `host` is docker host IP address (it may be `localhost`). Please, specify a port that is not taken by any process. Also, you will be prompted to enter a port where UTBot itself will be run. -5. Get access to the container via + The script will prompt you to enter docker image tag. You can find the most recent tag [here](https://github.com/UnitTestBot/UTBotCpp/pkgs/container/utbotcpp%2Fbase_env), for example `24-11-2021`. - `ssh utbot@host -p $port` - - If you are prompted a password, type in `utbot`. + Installer will ask about `ssh_port` on host machine. This port will be forwarded inside container's ssh port (by default `sshd` in container listens 2020). + You may then login inside docker via `ssh utbot@host -p $ssh_port`, where `host` is a host machine IP address. + > ⚠ Specify free port that is not in use on host machine! + + Also, you will be prompted to enter a gRPC port on host machine that will be forwarded inside container's 2121 port where UTBot listens gRPC requests. + > Script will run docker image, mount specified folder on host filesystem into container's filesystem and forward ports for ssh and gRPC. + + + +5. Login via ssh into newly started container + ``` + ssh utbot@host -p $ssh_port + ``` + > You can type `localhost` as `host` if you are inside terminal of a host machine) + > If you are prompted a password, enter `utbot`. -5. Clone UTBotCpp repository into home directory inside docker container, preferably with ssh. And don't forget to clone modules with `git submodule update --init --recursive` +5. Clone UTBotCpp repository into home directory **inside docker container**, preferably with ssh. + +And don't forget to clone modules with `git submodule update --init --recursive` 6. `cd` into `UTBotCpp` directory and run `build.sh` — it is the script that builds KLEE UTBot and runs UTBot unit tests 7. Navigate to `UTBotCpp/server/build` directory and launch the binary with `./utbot server` command. Now the server is running. 8. Launch VS Code on your local machine. Use VS Code [Remote-SSH](https://code.visualstudio.com/docs/remote/ssh) to get access to the docker insides. Navigate to `UTBotCpp/vscode-plugin` directory and run `build.sh` script. diff --git a/README.md b/README.md index bdca6a5e7..c49935216 100644 --- a/README.md +++ b/README.md @@ -24,11 +24,10 @@ UTBot is distrbuted as an archive that contains 4. A run script `unpack_and_run_utbot.sh`. To launch UTBot, `unzip` the archive and run the -`chmod +x unpack_and_run_utbot.sh && ./unpack_and_run_utbot.sh` command (we recommend doing it in a fresh directory to make UTBot removing easier). To remove UTBot, simply delete this directory. +`./unpack_and_run_utbot.sh` command (we recommend doing it in a fresh directory to make UTBot removing easier). To remove UTBot, simply delete this directory. To install UTBot VSCode plugin, use VSCode *Install from VSIX* command. ## How to contribute to UTBot -See [**DEVNOTE.md**](DEVNOTE.md) -and [**CONTRIBUTING.md**](CONTRIBUTING.md) \ No newline at end of file +See [**CONTRIBUTING.md**](Contributing guidelines) and [**Developer guide**](DEVNOTE.md) \ No newline at end of file diff --git a/SmokeTest.md b/SmokeTest.md index 03ed7bb3a..51f02391e 100644 --- a/SmokeTest.md +++ b/SmokeTest.md @@ -27,7 +27,7 @@ Move binary and script into a new separate directory and run installation script in it ``` cd utbot-release-version - chmod +x unpack_and_run_utbot.sh && ./unpack_and_run_utbot.sh + ./unpack_and_run_utbot.sh ``` Check process is up and running @@ -42,7 +42,7 @@ PID/port 2121 should be found -[ ] Perform client setup: - In local VSCode look for *Install from VSIX* command, select early downloaded ```utbot_plugin.vsix``` and install it - "UnitTestBot for C/C++" plugin should be visible in Extensions - - For Win: setup SSH remote connection with server - locally installed UTBot plugin should be available in remote mode (no new installation required) + - For Win: setup SSH remote connection with server![img.png](img.png)- locally installed UTBot plugin should be available in remote mode (no new installation required) - Open folder with source code, test connection as proposed, click Next and finish setup configuring project ##Check UTBot: Generate Tests diff --git a/docker/unpack_and_run_utbot.sh b/docker/unpack_and_run_utbot.sh old mode 100644 new mode 100755 diff --git a/docker/utbot_docker_dev.sh b/docker/utbot_docker_dev.sh index db659b29e..45921bf3c 100755 --- a/docker/utbot_docker_dev.sh +++ b/docker/utbot_docker_dev.sh @@ -14,7 +14,7 @@ read -e -p "Enter base image tag: " IMAGE_TAG IMAGE="ghcr.io/unittestbot/utbotcpp/base_env:$IMAGE_TAG" echo "Pulling docker image '$IMAGE'" -if ! docker pull $IMAGE > /dev/null; then +if ! docker pull $IMAGE ; then echo "Failed to fetch the image. Aborting.." exit 1 fi