Installation does not proceed as explained in the documentation

[domna]

When I follow the install instructions in the README the software is not able to run on my system. I had to do this additional steps to actual get the gui:

1. Do a pip install -r QuDAP/requirements.txt (because python tries to import PySide in instructions.py before the os call for pip install is run)
2. cd into the QuDAP directory
3. I needed to manually install pyvisa-py
4. Change the version check to version == "11" here

   QuDAP/QuDAP/GUI/VSM/VSM.py

   Line 18 in 237c244

   if version == "10" and build_number >= 22000:

While I could mediate these issues which can easily be fixed, I additionally think that the dependency management should be handled differently.

1. pip install should not be called on every start, because this could impact the software functionality in unforseen ways when packages are updated/changed. This would not be transparent to the user. Additonally, it is an unecesarry start overhead.
2. The list of dependencies should be specified in pyproject.toml
3. There should be a frozen list of dependencies to reproduce the dev environment. This can be generated with, e.g., pip-compile or uv. Maybe the hatchling build system has something similar, however, I'm not experienced with it so I can only recommend the other tools.

[domna]

One additional remark to the classifiers. I think this line

QuDAP/pyproject.toml

Line 13 in 237c244

"Operating System :: OS Independent",

should state that the software is build for windows (regarding the windows specific code and if conditions and the statement in the documentation that it is build for windows). This could later be extended when the software is ported and tested on other systems, too.

[CharlieGPA40]

Hi @domna

I have implemented a fix for this issue by:

1. Ensuring pip install is not executed at runtime.
   

   QuDAP/README.md

   Lines 64 to 90 in 15a22af

   	### 2. Option 2 - Clone the Repository
   	or installed from source:
   	```bash
   	git clone https://github.com/CharlieGPA40/QuDAP.git
   	cd QuDAP
   	pip install .
   	```
   	### 3. Generate Your Own Requirements File (Optional)
   	If you prefer installing pinned dependencies (exact versions for reproducibility), you can create a 'requirements.txt' from the 'pyproject.toml' using pip-tools. This way, you control which versions get installed without QuDAP shipping a pre-generated file.
   	1. Install 'pip-tools':
   	```bash
   	pip install pip-tools
   	```
   	2. Compile dependencies from 'pyproject.toml':
   	```bash
   	pip-compile --output-file requirements.txt pyproject.toml
   	```
   	### 4. Install Dependencies
   	You have two primary options:
   	1. Install 'pyproject.toml':
   	```bash
   	pip install .
   	```
   	This reads '[QuDAP] dependencies' in 'pyproject.toml' and installs the most recent compatible versions.
   	2. Install from your compiled 'requirements.txt' (for locked versions):

2. Adding dependency management via pyproject.toml.
   

   QuDAP/pyproject.toml

   Lines 16 to 17 in 15a22af

   	dependencies = [
   	"PyQt6",

3. Changing the Operating System to Windows.

QuDAP/pyproject.toml

Line 13 in 15a22af

"Operating System :: Microsoft :: Windows",

5. Providing instructions for users to generate their own requirements.txt using pip-tools.Let me know if you need any modifications.

QuDAP/README.md

Lines 71 to 81 in 15a22af

	### 3. Generate Your Own Requirements File (Optional)
	If you prefer installing pinned dependencies (exact versions for reproducibility), you can create a 'requirements.txt' from the 'pyproject.toml' using pip-tools. This way, you control which versions get installed without QuDAP shipping a pre-generated file.
	1. Install 'pip-tools':
	```bash
	pip install pip-tools
	```
	2. Compile dependencies from 'pyproject.toml':
	```bash
	pip-compile --output-file requirements.txt pyproject.toml
	```

Thanks for all your comment. Let me know if there is any more modifications needed.

Best regards,
Chunli Tang

[domna]

Hey @CharlieGPA40,

thank you for the changes. I'll check them soon when I have more time, just one small quick remark to point 5: In my view the requirements.txt is not for the user to generate their own dependencies. It is rather to be produced during development by you from pyproject.toml. That way any devs are able to reproduce your exact development environment (in case there are some dependency issues). It also serves to ensure that there are no dependency conflicts one might overlook. Often this is also used in CI/CD to get a reproducible build (otherwise ci can break just from a dependency changing). Of course there are limitations (e.g., fixed python version to generate the dependencies for) but in my view this is best practice for python projects.

[domna]

Hey,

thank you again for the changes! I had a deeper look now. First of all, I'm able to run the program without any additional changes or package installations 🥳.
However, there are still a few pitfalls following the installation steps:

1. I still had to do a cd QuDAP and then run python ./StartGUI.py. If I run it according to the documentation with python ./QuDAP/StartGUI.py I get the error FileNotFoundError: [Errno 2] No such file or directory: 'GUI/QSS/QListWidget.qss'
2. It's not clear how to run the program when installed from pip directly, because in this case the user doesn't have the folder present to run anything.
3. pip compile should be done during development to create a reproducible build of the software. This is mainly to help users or devs to create the same environment you had (in case a newer dependency breaks the software or else). There are also other tools which cover the whole build, dependency, testing lifecycle, i.e. poetry, uv, hatch, ... In my view these are not strictly necessary but a freezed list of packges should be there.

For 2. I recommend using the gui-scripts from the entry points specification in pyproject.toml. That way python automatically creates an executable shim for you with which you can start the program. Then users can install the software via pip and just execute the command in the shell.