Skip to content
Snippets Groups Projects

doc: add emulator usage instructions into the readme

Merged doc: add emulator usage instructions into the readme
update-docs into master
Merged Burak Hançerli requested to merge update-docs into master
Compare
and
1 file
+ 29
− 4
Compare changes
  • Side-by-side
  • Inline
README.md
+ 29
− 4
# Qt UI Viewer
![Qt UI Viewer](assets/PlayStoreFeatureImage.svg)
## About
@@ -13,6 +14,7 @@ You can get the pre-built app from either [Google Play Store][google-play-link]
## Prerequisites
* Qt Design Studio 4.7 or newer
* CMake 3.16 or newer
* Qt 6.8.0 or newer
* OpenSSL (<https://github.com/KDAB/android_openssl>)
@@ -81,7 +83,24 @@ cmake --build build
## Usage
Upload the final APK file to your Android device and run. Then follow the instructions within the app.
Upload the final APK file to your Android device or emulator and run. Then follow the instructions within the app.
### Running on Android Emulator
For creating and running an Android emulator, follow the instructions on the [avdmanager][avd-manager] and [emulator][android-emulator] pages. Please also make sure that [telnet][telnet-wiki] is installed on your system for [emulator console][emulator console] commands.
Android emulators run behind a [virtual router](https://developer.android.com/studio/run/emulator-networking) and network address translation (NAT) so they can't be accessed directly from the host machine. There is one TCP port required to be forwarded in between that virtual router and the host machine so that Qt Design Studio can communicate with the application.
After creating and spinning up the emulator, you can forward the required ports to the emulator with the following command on terminal:
> Note: This unfortunately needs to be repeated every time the emulator is started.
```bash
telnet localhost 5554 --> ( that will show you the file to get the auth code )
auth <auth-code>
redir add tcp:40000:40000
```
Then in the Qt Design Studio add a new device with the IP of 127.0.0.1
## Testing
@@ -94,11 +113,11 @@ npm i -g xunit-viewer
xunit-viewer -r output.junit.xml
```
It'll create a `report.html` file that can be opened in a web browser. For more information about `xunit-viewer` please visit the [GitHub repo](https://github.com/lukejpreston/xunit-viewer).
It'll create a `report.html` file that can be opened in a web browser. For more information about `xunit-viewer` please visit the [GitHub repo][xunit-viewer].
## Versioning
[android:versionCode](https://developer.android.com/guide/topics/manifest/manifest-element#vcode) is an integer value that should be incremented for each new release and it's required by Google Play Store. It's used to determine if the app should be updated or not.
[android:versionCode][manifest-vcode] is an integer value that should be incremented for each new release and it's required by Google Play Store. It's used to determine if the app should be updated or not.
During the development this value can be set to any arbitrary integer. But for the release it should be incremented. The value can be controlled by setting the CMake variable called `GOOGLE_PLAY_APP_VERSION` during the CMake configuration step.
@@ -108,7 +127,7 @@ It's easy for an individual developer to forget to increment it before the relea
android:versionCode = <total_number_of_tags> + 11
```
The value `11` is coming from the times where `GOOGLE_PLAY_APP_VERSION` was increased without creating a tag, so we have an offset in between the tag count and the actual value. From now on the value should be incremented by creating a new tag.
The magic value `11` is coming from the times where `GOOGLE_PLAY_APP_VERSION` was increased without creating a tag, so we have an offset in between the tag count and the actual value. From now on the value should be incremented by creating a new tag.
There's no `AndroidManifest.xml` file in the repository. `AndroidManifest.xml.in` file is used to generate the `AndroidManifest.xml` file during the configuration step. The `versionCode` value is set to the `GOOGLE_PLAY_APP_VERSION` and the `versionName` value is set to the output of the `git describe --always --tags` command.
@@ -126,3 +145,9 @@ Both values can be seen in the `AndroidManifest.xml` file after the CMake config
[google-play-link]: <https://play.google.com/store/apps/details?id=io.qt.qtdesignviewer>
[package-registry]: <https://git.qt.io/design-studio/design-viewer/qt-ui-viewer/-/packages>
[xunit-viewer]: <https://github.com/lukejpreston/xunit-viewer>
[manifest-vcode]: <https://developer.android.com/studio/publish/versioning>
[avd-manager]:<https://developer.android.com/tools/avdmanager>
[android-emulator]:<https://developer.android.com/studio/run/emulator-commandline>
[telnet-wiki]:<https://en.wikipedia.org/wiki/Telnet>
[emulator console]:<https://developer.android.com/studio/run/emulator-console>