Skip to content

Commit 375eb9f

Browse files
qwertygcqwertygc
authored
Update 2.1.-Installation.md
1 parent 2d9dcc6 commit 375eb9f

1 file changed

Lines changed: 283 additions & 9 deletions

File tree

‎docs/doc/en/2.1.-Installation.md‎

Lines changed: 283 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,72 @@ VLC is optional, but you will need it installed if you need to do any audio/vide
2828

2929
Alternatively, install from source code:
3030

31-
Download the source code. Read and apply the section for Windows source code installation in the **Readme.md** file. Remove the back-ticks that surround the command line instructions ` as these are used for display only.
31+
Use a virtual environment (commands in point 6 below). Not using a virtual environment may affect other Python software you may have installed.
32+
33+
1. Download and install the Python programming language. Please use a recent version on Windows. [Python3](https://www.python.org/downloads/). Download the latest "Windows installer (64-bit)" (or the one matching your architecture) for one of the above mentioned Python versions.
34+
35+
IMPORTANT: in the first window of the installation mark the option "Add Python to PATH"
36+
37+
2. Download the QualCoder software from: https://github.com/ccbogel/QualCoder from the Green Code button. This is the newest, but not yet officially released code (occasionally coding errors creep in). Click the green button "Code", and then "Download ZIP". **Alternatively**, choose the most recent release zip, see the right-hand side of this page for the link to Releases.
38+
39+
3. Unzip the folder to a location (e.g. downloads). (Tip, remove the doubled-up folder extraction QualCoder-master\QualCoder-master when asked where to extract. Just QualCoder-master).
40+
41+
4. Use the Windows command prompt. Type "cmd" in the Windows Start search engine, and click on the black software "cmd.exe" - the command console for Windows. In the console type or paste, using the right-click mouse copy and paste (ctrl+v does not work)
42+
43+
5. In the command prompt, move (using the `cd` command) into the QualCoder folder. You should be inside the QualCoder-master folder or if using a release (the Qualcoder-3.8.2 folder). e.g.
44+
45+
```bash
46+
cd Downloads\QualCoder-master
47+
```
48+
49+
5a. Instead of the next below commands, run the bat file which will run all these commands below, by typing this in and pressing Enter:
50+
51+
`run_from_source_Windows.bat`
52+
53+
If you get errors using a bat file, then run the below commands instead.
54+
55+
6. Install the virtual environment and required python modules.
56+
57+
58+
59+
The install may take up to 10 minutes. On some Windows systems you may need to replace the _python_ command with _py_ or _python3_ below:
60+
61+
```bash
62+
python -m venv env
63+
env\Scripts\activate
64+
python -m pip install --upgrade pip
65+
python -m pip install -r requirements.txt
66+
```
67+
68+
7. Start QualCoder. by moving to the the inner src folder first:
69+
70+
```bash
71+
cd src
72+
python -m qualcoder
73+
```
74+
75+
76+
8. If running QualCoder in a virtual environment, to exit the virtual environment type:
77+
78+
`deactivate`
79+
80+
The command prompt will then remove the *(env)* wording.
81+
82+
**To start QualCoder again**
83+
84+
If you are not using a virtual environment, as long as you are in the same drive letter, eg C:
85+
86+
`python -m qualcoder`
87+
88+
If you are using a virtual environment:
89+
90+
`cd` to the src folder inside the Qualcoder-master (or Qualcoder release folder):
91+
92+
```
93+
env\Scripts\activate
94+
cd src
95+
python -m qualcoder
96+
```
3297

3398
=== "MacOS"
3499

@@ -54,8 +119,68 @@ VLC is optional, but you will need it installed if you need to do any audio/vide
54119

55120
**Install from source code:**
56121

57-
Download the source code. Read and apply the section for macOS source code usage in the **Readme.md** file.
58-
Remove the back ticks that surround the command line instructions ` as these are used for display only.
122+
Use a virtual environment (commands in point 6 below). Not using a virtual environment may affect other Python software you may have installed.
123+
124+
1. Download and install the Python programming language. Please use Python 3.10, 3.11 or 3.12 on Windows, other versions may cause issues [Python3](https://www.python.org/downloads/macos/). Download the latest "macOS 64-bit universal2 installer" for one of the above mentioned Python versions and open it to install Python.
125+
126+
2. Download the QualCoder software from: https://github.com/ccbogel/QualCoder from the Green Code button. This is the newest, but not yet officially released code (occasionally coding errors creep in). Click the green button "Code", and then "Download ZIP". **Alternatively**, choose the most recent release zip, see the right-hand side of this page for the link to Releases.
127+
128+
3. Unzip the folder to a location (e.g. downloads) by double-clicking it.
129+
130+
4. Use the Terminal app (`Applications -> Utilities -> Terminal`).
131+
132+
5. In the terminal, move (using the `cd` command) into the QualCoder folder. You should be inside the QualCoder-master folder or if using a release (e.g. Qualcoder-3.8.2 folder). e.g.
133+
134+
```bash
135+
cd Downloads/QualCoder-master
136+
```
137+
138+
6. Install the virtual environment and required python modules.
139+
140+
The `python3` command uses the most recent installed version of Python. You can use a specific version on your macOS, if you have many Python versions installed, e.g. `python3.10`. To verify you are using the correct Python version type `which python3`, which should output: `/Library/Frameworks/Python.framework/Versions/3.<version>/bin/python3`. If the output is `/usr/bin/python3`, don't continue, since this is your system's Python and it is discouraged to use.
141+
142+
The install may take up to 10 minutes.
143+
144+
```bash
145+
python3 -m venv env # this creates the virtual environment with the name "env" in your current directory
146+
source env/bin/activate # this activates the virtual environment "env", (env) should appear in front of your prompt
147+
pip3 install --upgrade pip # optionally; pip and pip3 are equivalent withing a virtual environment
148+
pip3 install -r requirements.txt
149+
```
150+
151+
7. Run QualCoder from the command prompt
152+
153+
```bash
154+
cd src
155+
python3 -m qualcoder # python and python3 are equivalent withing a virtual environment
156+
```
157+
158+
8. If running QualCoder in a virtual environment, to exit the virtual environment type:
159+
160+
```bash
161+
deactivate
162+
```
163+
164+
The command prompt will then remove the *(env)* wording.
165+
166+
**To start QualCoder again**
167+
168+
If you are not using a virtual environment:
169+
170+
```bash
171+
cd Downloads/QualCoder-master
172+
cd src
173+
python3 -m qualcoder
174+
```
175+
176+
If you are using a virtual environment:
177+
178+
```bash
179+
cd Downloads/QualCoder-master
180+
source env/bin/activate
181+
cd src
182+
python3 -m qualcoder
183+
```
59184

60185

61186
=== "Debian / Ubuntu / Lubuntu / ZorinOS Linux"
@@ -64,18 +189,167 @@ VLC is optional, but you will need it installed if you need to do any audio/vide
64189

65190
Alternatively, run QualCoder from the source code:
66191

67-
Download the source code. Read and apply the section for Ubuntu source code usage in the **Readme.md** file. Remove the back ticks that surround the command line instructions ` as these are used for display only.
192+
To install from source code below, inside a virtual environment. If you are using the alternative Ubuntu Desktop manager **Xfce** you may need to run this: `sudo apt install libxcb-cursor0` If you are using audio or video, install VLC (download from site) or: `sudo apt install vlc`
193+
194+
0. Install pip. This is a tool that downloads extra python modules.
195+
196+
`sudo apt install python3-pip`
197+
198+
1. Download and unzip the Qualcoder folder.
199+
200+
2. Then `cd` to the QualCoder folder.
201+
202+
For example, you may now be in this folder, where you unzipped QualCoder:
203+
204+
yourcomputer:~Downloads/QualCoder-3.8.2
205+
206+
3a. Instead of the commands from 3b. onwards, run the shell file which will run all these below commands. Make this file executable (Righ-click and go to Properties), then type the below command and press Enter:
207+
208+
`./run_from_source_Linux.sh`
209+
210+
3b. Set up virtual environment and install python modules. The virtual environment will be in its own folder called env. Installing required modules takes a while.
211+
212+
```
213+
python3 -m venv env
214+
source env/bin/activate
215+
pip install --upgrade pip
216+
pip install -r requirements.txt
217+
```
218+
219+
5. Move to the inner src folder, then:
220+
```
221+
cd src
222+
python3 -m qualcoder
223+
```
224+
225+
6. After using QualCoder deactivate the virtual environment.
226+
227+
`deactivate`
228+
229+
**Usage any time after the install, move to the QualCoder folder then:**
230+
231+
```
232+
source env/bin/activate
233+
cd src
234+
python3 -m qualcoder
235+
```
236+
237+
To exit the environment:
238+
239+
`deactivate`
240+
241+
You can also make a .desktop file for launching QualCoder:
242+
243+
Create a .Desktop file for launch, enter this command (adapt it according to the location of the source code folder):
244+
245+
bash -c 'cd ~/.local/share/qualcoder/src/ && ~/.local/share/qualcoder/env/bin/python3.12 -m qualcoder'
246+
68247

69248
=== "Fedora Linux"
70249

71250
These instructions download the current source code directly from GitHub. Note: Fedora uses Wayland which may not work well with the Qt graphical interface. It is suggested you also install Xwayland.
72-
73-
Download the source code. Read and apply the section for Fedora source code usage in the **Readme.md** file.
74-
Remove the back ticks that surround the command line instructions ` as these are used for display only.
75251
**There is an ongoing problem with audio/video coding on Linux Fedora -- the software crashes.**
252+
253+
1. Download and unzip the Qualcoder folder.
254+
255+
2. Then `cd` to the QualCoder folder.
256+
257+
For example, you may now be in this folder, where you unzipped QualCoder:
258+
259+
yourcomputer:~Downloads/QualCoder-3.8.2
260+
261+
3a. Instead of the commands from 3b. onwards, run the shell file which will run all these below commands. Make this file executable (Right-click and select Properties), then type the below command and press Enter:
262+
263+
`./run_from_source_Linux.sh`
264+
265+
3b. Set up virtual environment and install python modules. The virtual environment will be in its own folder called env. Installing required modules takes a while.
266+
267+
```
268+
python -m venv env
269+
source env/bin/activate
270+
pip install --upgrade pip
271+
pip install -r requirements.txt
272+
```
273+
274+
3. Move to the inner src folder:
275+
276+
```
277+
cd src
278+
```
279+
280+
4 Then start QualCofder:
281+
282+
```
283+
python -m qualcoder
284+
```
285+
286+
5. After using QualCoder deactivate the virtual environment.
287+
288+
`deactivate`
289+
290+
6 .Usage any time after the install, move to the QualCoder folder then:
291+
292+
```
293+
source env/bin/activate
294+
cd src
295+
python3 -m qualcoder
296+
```
297+
298+
On finishing type `deactivate` to exit the virtual environment.
299+
76300

77301
=== "Arch/Manjaro Linux"
78302

79-
Download the source code. Read and apply the section for Arch source code usage in the **Readme.md** file.
80-
Remove the back ticks that surround the command line instructions ` as these are used for display only.
303+
If you are using audio or video, install VLC (download from site) or: `sudo pacman -S vlc`
304+
305+
0. Install pip and venv:
306+
307+
`sudo pacman -S python python-pip python-virtualenv`
308+
309+
1. Download and unzip the Qualcoder folder.
310+
311+
2. Then `cd` to the QualCoder folder.
312+
313+
For example, you may now be in this folder, where you unzipped QualCoder:
314+
315+
yourcomputer:~Downloads/QualCoder-3.8.2
316+
317+
3a. Instead of the commands from 3b. onwards, run the shell file which will run all these below commands. Make this file executable (Right-click and select Properties), then type the below command and press Enter:
318+
319+
`./run_from_source_Linux.sh`
320+
321+
3b. Set up virtual environment and install python modules. The virtual environment will be in its own folder called env. Installing required modules takes a while.
322+
323+
```
324+
python -m venv env
325+
source env/bin/activate
326+
pip install --upgrade pip
327+
pip install -r requirements.txt
328+
```
329+
330+
3. Move to the inner src folder:
331+
332+
```
333+
cd src
334+
```
335+
336+
4 Then start QualCofder:
337+
338+
```
339+
python -m qualcoder
340+
```
341+
342+
5. After using QualCoder deactivate the virtual environment.
343+
344+
`deactivate`
345+
346+
6 .Usage any time after the install, move to the QualCoder folder then:
347+
348+
```
349+
source env/bin/activate
350+
cd src
351+
python3 -m qualcoder
352+
```
353+
354+
On finishing type `deactivate` to exit the virtual environment.
81355

0 commit comments

Comments
 (0)