From f415088ef39f1ebf0d8fc6d7dbb2d5796a7c2b9b Mon Sep 17 00:00:00 2001 From: Bindea Cristian Date: Tue, 21 Jan 2025 17:56:26 +0200 Subject: [PATCH] docs: add build instructions for Linux, Windows and macOS Signed-off-by: Bindea Cristian --- ci/macOS/package_darwin.sh | 7 +- ci/x86_64/x86-64_appimage_process.sh | 3 +- .../build_instructions/linuxBuild.rst | 244 ++++++++++++++++++ .../build_instructions/macosBuild.rst | 55 ++++ .../build_instructions/windowsBuild.rst | 213 +++++++++++++++ docs/user_guide/index.rst | 6 +- 6 files changed, 524 insertions(+), 4 deletions(-) create mode 100644 docs/user_guide/build_instructions/linuxBuild.rst create mode 100644 docs/user_guide/build_instructions/macosBuild.rst create mode 100644 docs/user_guide/build_instructions/windowsBuild.rst diff --git a/ci/macOS/package_darwin.sh b/ci/macOS/package_darwin.sh index b6b390a3f3..70c5940a74 100755 --- a/ci/macOS/package_darwin.sh +++ b/ci/macOS/package_darwin.sh @@ -142,6 +142,9 @@ echo $STAGING_AREA_DEPS/lib | dylibbundler -ns -of -b \ echo "=== Bundle the Qt libraries & Create Scopy.dmg" macdeployqt Scopy.app -verbose=3 -zip -Xvr ScopyApp.zip Scopy.app -macdeployqt Scopy.app -dmg -verbose=3 + +if [ "$TF_BUILD" == "true" ];then + zip -Xvr ScopyApp.zip Scopy.app + macdeployqt Scopy.app -dmg -verbose=3 +fi popd diff --git a/ci/x86_64/x86-64_appimage_process.sh b/ci/x86_64/x86-64_appimage_process.sh index 266274652f..a782e8ebae 100755 --- a/ci/x86_64/x86-64_appimage_process.sh +++ b/ci/x86_64/x86-64_appimage_process.sh @@ -5,7 +5,8 @@ set -ex USE_STAGING=OFF ## -SRC_DIR=$(git rev-parse --show-toplevel 2>/dev/null ) || echo "No source directory found" +SRC_DIR=$(git rev-parse --show-toplevel 2>/dev/null ) || \ +SRC_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && cd ../../ && pwd ) SRC_SCRIPT=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) if [ "$CI_SCRIPT" == "ON" ]; then diff --git a/docs/user_guide/build_instructions/linuxBuild.rst b/docs/user_guide/build_instructions/linuxBuild.rst new file mode 100644 index 0000000000..c1f12a8709 --- /dev/null +++ b/docs/user_guide/build_instructions/linuxBuild.rst @@ -0,0 +1,244 @@ +.. _linux_build_instructions: + + +Linux Build Instructions +========================== + + +Qt Setup Instructions +---------------------- + +Before building Scopy on a Linux system, ensure all necessary requirements are installed. +One key prerequisite is installing the Qt Framework (LTS version 5.15), which can be done using either the online or offline installer available on the official `Qt Downloads page `_. + +If you want to continue the development of the Scopy application, we recommend using the Qt Creator. +This can be installed with the official installer from `Qt Downloads page `_, just make sure to also select the Qt Creator, alongside the Qt libraries, in the Qt Maintenance tool. + +Another way to install the Qt Framework is to use the unofficial Qt CLI Installer `aqtinstall `_. +Note that this method is not recommended if you want to continue developing the Scopy application or any other application that uses the Qt Framework. For a more secure method use the official installer. + + +To use aqtinstall, first clone the Scopy repository. With Python3 installed, execute the following command: + +.. code-block:: bash + + $ scopy/ci/ubuntu/ubuntu_build_process.sh install_qt + + +Building Scopy +--------------- + +After the Qt installation is complete you can start following the next steps: + +1. If not done yet, clone the Scopy repository: + + .. code-block:: bash + + $ cd ~ + $ git clone https://github.com/analogdevicesinc/scopy.git + + +2. Set up dependencies. + + - Run the following script with its respective arguments: + + .. code-block:: bash + + $ scopy/ci/ubuntu/ubuntu_build_process.sh install_packages build_deps + + + This will install all packages needed to build the Scopy application. Note that this process may take a long time since Scopy requires many libraries to function properly. + + This script will require administrative rights to copy the libs and headers to known paths: `/usr/local/lib` and `/usr/local/include`. + If you don't want that to happen, you can edit in the script the line that contains `USE_STAGING=OFF` to `USE_STAGING=ON`. + But this will make the build process even more difficult and will not be covered in this tutorial. + + +3. Build the application. + + - From the root of the repository, create a build folder: + + .. code-block:: bash + + $ cd ~/scopy + $ mkdir build + $ cd build + + - From inside the build folder, execute CMake and point to the root of the repository: + + .. code-block:: bash + + $ cmake -DCMAKE_PREFIX_PATH=/opt/Qt/5.15.2/gcc_64 ../ + + Depending on where you installed Qt, you may need to tell cmake where it was installed. + If everything goes well, it should say `"Configuring done"` and `"Generating done"`. + + - After CMake completes, execute: + + .. code-block:: bash + + $ make + + This will compile the entire project. The process may take 15 minutes or more, depending on your CPU. + To speed up the process, you can run make with ``-j`` argument followed by the number of threads that you want to use to build the app: ``make -j14`` + + At the end of the build, an executable will be available, named simply: `scopy`. + + This can be run from the terminal and it should start the Scopy GUI. + + +Qt Creator project configuration +-------------------------------- + +In order to streamline the development of the Scopy application, we recommend using the `Qt Creator IDE `_. + +To start using Qt Creator for development, you have to first install all dependencies needed to build Scopy. To make sure you have this done right, follow the `Building Scopy`_ tutorial from above. + +After that, open Qt Creator and click **Open Project**. Navigate to the location where you cloned Scopy and select the **CMakeLists.txt** file. Last step is to click **configure**, and Qt Creator should be able to build the application at the press of a button. +If there are errors at the building phase, try to first make a build manually from the terminal using the steps in `Building Scopy`_, and inside the Qt Creator, select the build foler and click **Configure**. + +After completing these steps, Qt Creator will be ready to build the Scopy application. + +Creating an Installer for x86_64 architecture +--------------------------------------------- + +If you want to create a Scopy installer for the Linux x86_64 architecture, you have two options: `AppImage` or `Flatpak`. + + +AppImage +"""""""" +An `AppImage `_ is a self-contained file that includes all the necessary components for an application to run. +Once made executable and launched, the AppImage directly opens the application. + +- To create a Scopy AppImage you will need the Scopy build dependencies to be already build and installed. If they are not installed, run the commad + +.. code-block:: bash + + $ scopy/ci/ubuntu/ubuntu_build_process.sh install_packages build_deps + +- After this step is completed, Scopy AppImage can be generated using the command: + +.. code-block:: bash + + $ scopy/ci/x86_64/x86-64_appimage_process.sh install_packages run_workflow + +This will download the packaging tools and use them to create an Scopy-x86_64.AppImage that can be easily distributed. + + +Flatpak +""""""" + +An `Flatpak `_ +- To use a Flatpak application, you first want to install the flatpak cli using the `instructions `_. + +- After that to use Flatpak for building an installer you will need to install the following packets and runtimes. + +.. code-block:: bash + + $ sudo apt install -y build-essential subversion mm-common jq flatpak-builder + $ sudo flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo + $ sudo flatpak install flathub org.kde.Platform//5.15-23.08 -y + $ sudo flatpak install flathub org.kde.Sdk//5.15-23.08 -y + +- After the installation is complete just run the script: + +.. code-block:: bash + + $ scopy/ci/flatpak/flatpak_build_process.sh + +This process will take some time because the flatpak build system will compile all dependencies needed for Scopy before packaging the application. + + +Creating an Installer for other architectures +--------------------------------------------- + +The Scopy application provides support for Linux on different architectures: `x86_64`, `armhf` and `arm64`. +The tutorial for building an installer for `x86_64` was presented above. + +The Scopy installer for other architectures can be done locally on the host operating system, but it is out of the scope of this tutorial. +A shortcut that can be taken here is to download the Docker Image that is already configured to build and package the Scopy application. +All Docker Images are hosted on `Dockerhub `_, and can be freely downloaded. The recipe for each image can be found inside the `Scopy `_ repository. + +Next, a temporary Docker volume is created to link the local environment with the Docker container. +The compilation process takes place inside the container using the pre-configured filesystem. +This Docker volume will include the previously cloned Scopy repository. + + +Installer for armhf +"""""""""""""""""""" + +1. The first step is to clone the Scopy repository, if not cloned yet + + .. code-block:: bash + + $ cd ~ + $ git clone https://github.com/analogdevicesinc/scopy.git + +2. Download the Docker image + + .. code-block:: bash + + $ docker pull cristianbindea/scopy2-armhf-appimage:latest + +3. Run the image, while creating a docker volume + + .. code-block:: bash + + $ docker run -it --mount type=bind,source=~/scopy,target=/home/runner/scopy cristianbindea/scopy2-armhf-appimage:latest + + Now this repository folder it shared with the Docker container. + +4. To compile and package the application use + + .. code-block:: bash + + $ scopy/ci/arm/arm_build_process.sh arm32 run_workflow + + +Finally, after the development is done use this to clean the system: + +.. code-block:: bash + + $ docker container ls -a # get the container id + $ docker container rm -v (container id) + $ docker image rm cristianbindea/scopy2-arm32-appimage:latest + + +Installer for arm64 +"""""""""""""""""""" + +1. The first step is to clone the Scopy repository, if not cloned yet + + .. code-block:: bash + + $ cd ~ + $ git clone https://github.com/analogdevicesinc/scopy.git + +2. Download the Docker image + + .. code-block:: bash + + $ docker pull cristianbindea/scopy2-arm64-appimage:latest + +3. Run the image, while creating a docker volume + + .. code-block:: bash + + $ docker run -it --mount type=bind,source=~/scopy,target=/home/runner/scopy cristianbindea/scopy2-arm64-appimage:latest + + Now this repository folder it is shared with the Docker container. + +4. To compile and package the application use + + .. code-block:: bash + + $ scopy/ci/arm/arm_build_process.sh arm64 run_workflow + + +Finally, after the development is done use this to clean the system: + +.. code-block:: bash + + $ docker container ls -a # get the container id + $ docker container rm -v (container id) + $ docker image rm cristianbindea/scopy2-arm64-appimage:latest diff --git a/docs/user_guide/build_instructions/macosBuild.rst b/docs/user_guide/build_instructions/macosBuild.rst new file mode 100644 index 0000000000..d657422c39 --- /dev/null +++ b/docs/user_guide/build_instructions/macosBuild.rst @@ -0,0 +1,55 @@ +.. _macos_build_instructions: + +MacOS Build Instructions +========================== + +.. caution:: + + The process of building and correctly linking the application and it's dependencies is complex and very error prone. + To simplify the process we created a series of bash scripts that take care of this, the downside is that compiling and packaging takes a lot of time. + Currently without modifying the source code you can only build the application for intel x86_64 processors. + We are working to optimize this build procedure. + + +Building Scopy +----------------------- + +1. Clone the Scopy repository: + + .. code-block:: zsh + + % cd ~ + % git clone https://github.com/analogdevicesinc/scopy.git + + +2. Set up dependencies. + + - Run the following script: + + .. code-block:: zsh + + % scopy/ci/macOS/install_macos_deps.sh + + This will install packages using brew, so you will have to make sure that you have brew installed on the machine. Here are the `install instructions `_. The rest of the dependencies that can't be found on brew will be built from the source files. + +3. Build the application + + - Run the following script: + + .. code-block:: zsh + + % scopy/ci/macOS/build_azure_macos.sh + + This will use the packages from `Step 2` in order to compile the Scopy application. + +4. Package the application + + - Run the following script: + + .. code-block:: zsh + + % scopy/ci/macOS/package_darwin.sh + + To run the application, the final step is linking the dependencies to the Scopy binary, enabling the operating system to locate them at runtime. + + This process is handled by a script that manages both the linking and packaging. Once the script completes, inside the build folder, it generates a file named **Scopy.app**, which can be opened either by running **"open Scopy.app"** in the terminal or by double-clicking it in the file explorer. \ No newline at end of file diff --git a/docs/user_guide/build_instructions/windowsBuild.rst b/docs/user_guide/build_instructions/windowsBuild.rst new file mode 100644 index 0000000000..5a0929335a --- /dev/null +++ b/docs/user_guide/build_instructions/windowsBuild.rst @@ -0,0 +1,213 @@ +.. _windows_build_instructions: + +Windows Build Instructions +========================== + + +Building Scopy +----------------------- + +In order to emulate a UNIX-like environment for building Scopy on Windows, we use MSYS2. + +To install MSYS2, follow these instructions: `MSYS2 Installation `_. +We suggest installing the MSYS2 in root of the **C:\\** partition. In this tutorial the MSYS2 install path is **C:\\msys64**, if you choose a different install directory, make sure to also update the paths. + +.. tip:: + Open the **MINGW64** shell of MSYS2. Other terminals will not work! + +1. Clone the Scopy repository: + + .. code-block:: bash + + $ cd ~ + $ git clone https://github.com/analogdevicesinc/scopy.git + +2. Set up dependencies: + + - Execute the script: + + .. code-block:: bash + + $ scopy/ci/windows/windows_build_process.sh + + This will install all packages needed to build the Scopy application. Note that this process may take a long time since Scopy requires many libraries to function properly. + +3. Build the application: + + - From the root of the repository, create a build folder: + + .. code-block:: bash + + $ cd ~/scopy + $ mkdir build + $ cd build + + - From inside the build folder, execute CMake and point to the root of the repository: + + .. code-block:: bash + + $ cmake -GNinja ../ + + If everything goes well, it should say "Configuring done" and "Generating done." + - After CMake completes, execute: + + .. code-block:: bash + + $ ninja + + +This will compile the entire project. The process may take 15 minutes or more, depending on +your CPU. At the end of the build, two executables will be available: `scopy.exe` and `scopy-console.exe`. +Both start the application, but the latter runs Scopy in debug mode. + + +Running Scopy +----------------------- + +To run Scopy, it is required to first set a few environment variables. To do that, click on the Start menu and search for "environment". +The option "Edit environment variables for your account" should appear; Click on it. + +You will need to create two environment variables: **PATH** and **SCOPY_PYTHONPATH**. + +We assume that MSYS2 installation path is **C:\\msys64**, if have chosen a different install directory, make sure to also update the paths. + +1. Add the **PATH** variable: + + - Click on **"New..."** + - In **"Variable name:"**, write ``PATH`` + - In **"Variable value:"**, write: ``%PATH%;C:\msys64\mingw64\bin`` + - Click **OK**. + +2. Add the **SCOPY_PYTHONPATH** variable: + + - For this variable you would need to check that the python version installed in MINGW64. To do this run the command: + + .. code-block:: bash + + $ python --version + + - Click on **"New..."** + - In **"Variable name:"**, write ``SCOPY_PYTHONPATH`` + - In **"Variable value:"**, write the line below. Also update the python version if needed. + + .. code-block:: + + C:\msys64\mingw64\lib\python3.11;C:\msys64\mingw64\lib\python3.11\plat-win;C:\msys64\mingw64\lib\python3.11\lib-dynload;C:\msys64\mingw64\lib\python3.11\site-packages + + - Click OK. + +Once these steps are complete, the Scopy you built should run. Using File Explorer, navigate to: + +.. code-block:: + + /mingw64/home/scopy/build + +- Double-click on **scopy.exe**. + + +Windows Qt Setup Instructions +----------------------------- + +To avoid using the MSYS terminal for rebuilding the app, you can use Qt Creator instead. Follow the steps below to set up and use Qt Creator: + +1. Install Qt Creator: + + - Download the Qt Creator installer (offline or online) from the official `Qt Downloads page `_. + - During the installation process, select only the **Qt Creator** option. This ensures that only the Qt Creator IDE is installed. The necessary Qt libraries will be sourced from the MSYS2 folder. + - Once the installation is complete, open Qt Creator. + +2. Initial Configuration for Scopy Application: + + - Follow the steps outlined in the `Building Scopy`_ section to set up the environment. + +3. Configure the Project in Qt Creator: + + Considering that you already done a build from the MINGW64 terminal. If not, follow the steps from `Building Scopy`_ + + - Open Qt Creator and click **Open Project**. + - Navigate to the MSYS2 installation directory and locate the Scopy project files. The typical path structure is: + + .. code-block:: + + /mingw64/home/scopy/build + + - Select the build folder and click **Configure**. + +After completing these steps, Qt Creator will be ready to build the Scopy application, streamlining the process compared to using the MSYS terminal. + + +Creating an Installer +---------------------------- + +To create an installer, the first step is to install the `Inno Setup Compiler `_. + +After that, there is only one more step: + +- Run the command: + + .. code-block:: bash + + $ scopy/ci/windows/build_and_create_installer.sh run_workflow + +This script will build the Scopy application and package it into a `Scopy-installer.exe` file. This file contains all the necessary components for Scopy to run properly, making it easy to redistribute. + + +Building Scopy using the Docker Image +--------------------------------------- + +Another way to build the Scopy application is by using pre-configured Docker images. A Docker image +is essentially a snapshot of an operating system that includes all the libraries and dependencies required to build the application. + +This tutorial has only two requirements: + +- `Git `_: Used to download the source code from GitHub. +- `Docker Desktop `_: Used to download and run the Docker image. + +To simplify the process, you can download a pre-configured Docker image specifically set +up to build and package the Scopy application. These Docker images are hosted on `Docker Hub `_ +and are free to download. Additionally, the recipe for each image is available in the `Scopy repository `_. + +After you have installed Docker Desktop, the next steps will be run inside a powershell terminal. + +1. Clone the Scopy repository + + .. code-block:: powershell + + > git clone https://github.com/analogdevicesinc/scopy.git + +2. Download the Docker Image + + .. code-block:: powershell + + > docker pull cristianbindea/scopy2-mingw64:latest + +3. Start the Docker Image + + Once the image is downloaded, you will create a temporary Docker volume to + connect your local environment with the Docker container. + + The compilation process takes place inside the container using its pre-configured + filesystem. The Docker volume will include the previously cloned Scopy repository to ensure everything is in sync. + + Make sure to update the source path to actual repository location. + + .. code-block:: powershell + + > docker run -it --mount type=bind,source=C:\Users\analog\scopy,target=/home/runner/scopy cristianbindea/scopy2-mingw64:latest + + Now this repository folder it is shared with the Docker container. + +4. Run the build script + + - From inside the Docker Image, run the build script: + + .. code-block:: powershell + + > C:\msys64\usr\bin\bash.exe -c '/home/docker/scopy/ci/windows/build_and_create_installer.sh run_workflow' + + This script will build and package the application. + +5. Locate the binary file + + After the script has finished running, you can install, or open the Scopy application. + Enter the repository location using File Explorer and you will find the Scopy installer `Scopy-installer.exe`. diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst index 5d6f883b20..c0b00f5bd5 100644 --- a/docs/user_guide/index.rst +++ b/docs/user_guide/index.rst @@ -446,8 +446,12 @@ User guide on how to use scripts with Scopy: Building from source --------------------------------------------------------------------- -Complete Scopy v2.0.0 build guides **coming soon**! +.. toctree:: + :titlesonly: + build_instructions/windowsBuild + build_instructions/linuxBuild + build_instructions/macosBuild Source code ---------------------------------------------------------------------