====== Installation Guide ======

===== Prerequisites for Running from Source =====

==== macOS Users ====

**PyRDPConnect** requires XQuartz to function correctly on macOS. XQuartz is an open-source version of the X.Org X server, a component necessary for running remote desktop applications.

=== Step 1: Install XQuartz ===

  - Visit the official XQuartz website: [[https://www.xquartz.org/|XQuartz Download Page]].
  - Download and install the latest version of XQuartz.
  - (Optional) Restart your computer to ensure all necessary components are initialized.

**Why XQuartz?**
XQuartz provides the necessary X11 environment that FreeRDP relies on for graphical rendering on macOS. Without it, the application may not display the RDP session correctly.

=== Step 2: Install Python and Required Packages ===

<code sh>
brew install python3
pip3 install pyqt5
</code>

=== Step 3: Clone the Repository and Run from Source ===

  - Clone the PyRDPConnect repository: <code sh>git clone https://github.com/LaswitchTech/PyRDPConnect.git</code>
  - Navigate to the ''src'' directory and execute the application: <code sh>python3 src/client.py</code>

==== Linux Users ====

For Linux users, **PyRDPConnect** requires Python 3, PyQt5, and FreeRDP to function correctly.

=== Step 1: Install Required Packages ===

Update your package list and install the necessary packages:

<code sh>
sudo apt-get update
sudo apt-get install -y git python3 python3-pip python3-pyqt5 python3-pyqt5.qtquick python3-pyqt5.sip freerdp2-x11
</code>

=== Step 2: Clone the Repository and Run from Source ===

  - Clone the PyRDPConnect repository: <code sh>git clone https://github.com/LaswitchTech/PyRDPConnect.git</code>
  - Navigate to the ''src'' directory and execute the application: <code sh>python3 src/client.py</code>

===== Running the Pre-Built Application =====

==== macOS Users ====

**PyRDPConnect** is available as a pre-built macOS application (''.app''). Before using the application, you must install XQuartz.

=== Step 1: Install XQuartz ===

  - Visit the official XQuartz website: [[https://www.xquartz.org/|XQuartz Download Page]].
  - Download and install the latest version of XQuartz.
  - (Optional) Restart your computer to ensure all necessary components are initialized.

=== Step 2: Run the PyRDPConnect Application ===

  - Locate the ''PyRDPConnect.app'' in the ''dist/macos'' directory or where you saved it.
  - Double-click the application to launch it.
  - **PyRDPConnect** should now open and run as expected.

**Troubleshooting**: If **PyRDPConnect** does not open or shows an error related to X11 or XQuartz, ensure that XQuartz is installed and running. You can manually start XQuartz from your Applications folder (''/Applications/Utilities/XQuartz.app'').

==== Linux Users ====

**PyRDPConnect** is also available as a pre-built single-file executable on Linux.

=== Step 1: Download and Install Dependencies ===

Make sure FreeRDP is installed:

<code sh>
sudo apt-get install -y freerdp2-x11
</code>

=== Step 2: Run the PyRDPConnect Executable ===

  - Locate the ''PyRDPConnect'' executable in the ''dist/linux'' directory or where you saved it.
  - Make the file executable if it’s not already: <code sh>chmod +x dist/linux/PyRDPConnect</code>
  - Run the application: <code sh>./dist/linux/PyRDPConnect</code>

===== Troubleshooting Common Issues =====

**Permission Denied Error**: If you encounter a "Permission denied" error, ensure that the script has executable permissions:
<code sh>
chmod +x <script_name>.sh
</code>

**XQuartz Issues**: If XQuartz does not start automatically, you can manually start it from ''/Applications/Utilities/XQuartz.app''.

===== Additional Information =====

If you have any questions or need further assistance, feel free to open an issue in the [[https://github.com/LaswitchTech/PyRDPConnect/issues|GitHub Repository]].