Copyedit building the GUI

Author: Tom-Willemsen

doc/Client.md

@@ -6,7 +6,7 @@
 :glob:
 :titlesonly:
 
-client/GUI-Getting-Started
+client/GUI-Building
 client/GUI-Coding
 client/GUI-Testing
 client/GUI-Eclipse

doc/Script-Generator.md

@@ -22,7 +22,7 @@ script_generator/*
 | Standalone app build directories | `base/uk.ac.isis.scriptgenerator/*` |
 
 ## Eclipse build
-To build and run the app through eclipse, the script generator product is found in `base\uk.ac.stfc.isis.scriptgenerator.client.product`. The instructions for setting up eclipse and loading the target platform (necessary for the script generator) are found in the instructions for the [main IBEX GUI setup](/client/getting_started/Building-the-GUI)
+To build and run the app through eclipse, the script generator product is found in `base\uk.ac.stfc.isis.scriptgenerator.client.product`. The instructions for setting up eclipse and loading the target platform (necessary for the script generator) are found in the instructions for the [main IBEX GUI setup](/client/build/Building-the-GUI)
 
 {#scriptgenerator_enable_perspective}
 ### Adding the perspective into the client

doc/client/GUI-Building.md

@@ -0,0 +1,8 @@
+# Building
+
+```{toctree}
+:glob:
+:titlesonly:
+
+compiling/*
+```

doc/client/GUI-Getting-Started.md

@@ -11,6 +11,15 @@ The following pages also contain GUI troubleshooting information for specific pr
 troubleshooting/*
 ```
 
+## Display resolution & scaling
+
+If the GUI loads up but items are the wrong size, you may need to change your display settings. The exact settings that
+you need may vary from computer to computer. This is a common issue on Windows 10 machines due to the OS' scaling
+setting for text, icons etc. that is meant to ensure they do not look too small on high screen resolutions. 
+
+Generally a resolution of 1920 x 1080 with a scaling factor of 100% should look correct on standard screens. You can
+increase both of those settings slightly if you feel like the display elements look uncomfortably small.
+
 ## IBEX appears fullscreen with top menu items hidden
 
 Solution: right click inside any OPI and select "exit full screen".
@@ -95,7 +104,6 @@ Add `Eclipse-BundleShape: dir` in the `MANIFEST.MF`; see the `.opis` `MANIFEST.M
 This makes the maven build build the directory into a directory rather than a jar, which is sometimes necessary to let eclipse then "see" the files natively on the filesystem. If you look in the `plugins/` folder of a built client you should see a folder for `.opis` but a `.jar` for most other ibex modules - except for a few that need to be built as directories, as you may be finding.
 
 
-
 ## Other issues
 ### Remote debugging with Eclipse
 The following has been done to ensure that it is possible to debug the IBEX GUI running on any particular instrument:

doc/client/GUI-Troubleshooting.md

@@ -0,0 +1,123 @@
+# Building the GUI
+
+:::{important}
+Before following this guide, ensure you have completed the following steps from
+[the first-time installation guide](/overview/First-Time-Build):
+- [Install Java JDK](#first_time_install_java)
+- [Install Maven](#first_time_install_maven)
+- [Install Git](#first_time_install_git)
+- [Install Python (Uktena)](#first_time_install_uktena)
+:::
+
+{#gui_build_checkout_code}
+## Checking out the code
+
+Development builds of the IBEX GUI are conventionally located in `c:\instrument\dev`. Create this folder if it
+doesn't already exist.
+
+From a windows command prompt, navigate to `c:\instrument\dev` and run:
+
+```
+git clone --recursive https://github.com/ISISComputingGroup/ibex_gui.git
+```
+
+The code for the IBEX GUI will now be located in `c:\instrument\dev\ibex_gui`.
+
+A [pre-commit hook](https://github.com/ISISComputingGroup/IBEX/issues/4786) should now be installed; to do this, run:
+
+```
+cd c:\instrument\dev\ibex_gui\build
+install_pre_commit_hook.bat
+```
+
+{#gui_build_install_eclipse}
+## Installing Eclipse
+
+You must use a version of eclipse which supports the RCP and Java versions currently in use by the client. There are
+two options for this:
+- Use the most recent version in `\\isis\inst$\Kits$\CompGroup\ICP\Developer Tools`
+- Download a recent Eclipse version directly from
+[the eclipse website](https://www.eclipse.org/downloads/packages/); choose the package for "RCP and RAP developers"
+
+By convention eclipse versions are installed into `c:\tools`, for example in 
+`c:\tools\eclipse-rcp-2024-06-R-win32-x86_64`.
+
+After installing eclipse from either of the above sources, you will need to add the line
+```
+-Djdk.util.zip.disableZip64ExtraFieldValidation=true
+``` 
+to the end of `eclipse.ini` (located next to the `eclipse.exe` executable), if it is not already present.
+
+{#gui_build_via_eclipse}
+## Building in Eclipse
+
+The first time the Eclipse IDE is started, it will ask you for a folder to use as a workspace. 
+Unless you have a specific reason to choose a different location, use `c:\Instrument\dev\eclipse_workspaces\ibex_gui` 
+(create this folder if it doesn't already exist).
+
+![](eclipse_workspace_selection.png)
+
+From the menu bar choose File -> Import -> General -> Existing Projects into Workspace.
+Choose "Select root directory" and browse to `c:\Instrument\dev\ibex_gui\base`. You should now see a list of plugins 
+to import with names like `uk.ac.stfc.isis.ibex.*`. Eclipse should automatically select everything so you just need 
+to click "Finish" to add them to the project. 
+
+:::{tip}
+If "Marketplace solutions available" dialogues appear, click cancel as these will be obtained later.
+:::
+
+<img src="eclipse_import_ibex_gui.png" width=400>
+
+From the "Project Explorer" tab on the left, expand the target platform folder (labelled as 
+`uk.ac.stfc.isis.ibex.targetplatform`), double click on the `targetplatform.target` file and choose 
+"Set as Active Target Platform". This may take some time as dependencies are downloaded - there is a progress bar
+in the very bottom-right of the Eclipse IDE.
+
+Once the target platform has finished downloading, the target platform view should look like this:
+
+<img src="eclipse_target_platform_view.png" width=600>
+
+To run the application from within Eclipse: open `ibex.product` from the `uk.ac.stfc.isis.ibex.e4.client.product`
+folder, select "Launch an Eclipse application". The IBEX GUI should now open.
+
+Next, From the menu bar choose Run->Run configurations and select `ibex.product` from the left hand list under 
+"Eclipse Application". In the "Main" tab, in **Run configurations**, tick the "Clear" tick box and untick the 
+"Ask for confirmation before clearing".
+
+<img src="eclipse_clear_workspace.png" width=400>
+
+In the "Configuration" tab tick the "Clear the configuration area before launching" tick box. 
+Click "Apply" and select "Run".
+
+:::{tip}
+If you see a `java.lang.UnsupportedClassVersionError` error:
+- Select Window -> Preferences -> Java -> Compiler
+- Set compliance level to 21.
+:::
+
+:::{tip}
+If you see a "Plugin execution not covered by lifecycle configuration" error:
+- From the menu bar choose: Window -> Preferences -> Maven -> Errors/Warnings
+- Set "Plugin execution not covered by lifecycle configuration" to Ignore
+:::
+
+Lastly, you should [set up checkstyle](../eclipse/Checkstyle-setup).
+
+If you did not manage to build or launch the IBEX client using these steps, there are troubleshooting notes for eclipse
+[here](../eclipse/Common-Eclipse-Issues) and for the GUI in general [here](../GUI-Troubleshooting).
+
+{#gui_build_via_maven}
+## Building via Maven
+
+Firstly, ensure you have a recent Maven version installed. Generally a suitable version will be the highest version
+number in `\\isis\inst$\Kits$\CompGroup\ICP\Binaries`. You can double-check your current Maven version by running
+`mvn -v` in a command prompt.
+
+To build using Maven, run:
+
+```
+cd c:\Instrument\dev\ibex_gui\build
+build.bat
+```
+
+Once the build finishes, the IBEX client executable can be found in `.\built_client\`.

doc/client/compiling/Building-the-GUI.md

@@ -1,18 +1,17 @@
 # Maven and Tycho
 
-The IBEX GUI is built using Tycho which is an extension of Maven designed for building Eclipse RCP products.
+The IBEX GUI is built using Tycho, which is an extension of Maven designed for building Eclipse RCP products.
 
 This document provides a brief overview of both Maven and Tycho.
 
 ## Maven ##
 
 The official description:
 
-_Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information._
+> _Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model
+> (POM), Maven can manage a project's build, reporting and documentation from a central piece of information._
 
-In simple terms:
-
-_Maven is a build automation tool used primarily for Java projects._
+In simple terms, Maven is a build automation tool used primarily for Java projects.
 
 ### What is a POM file? ###
 An XML file that describes the software project being built, its dependencies on other external modules and components, the build order, directories, and required plug-ins.