Merge pull request #9 from ISISComputingGroup/gui_copyedit

Copyedit GUI building section

Author: iangillingham-stfc

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/Editing-the-Wiki.md

@@ -146,3 +146,11 @@ This is a tip!
 :::
 
 The list of supported admonitions is [on the MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html).
+
+## Removing & deleting pages
+
+When moving pages, it is helpful to add redirects to the new location, so that links external to the wiki continue to
+work. To do this, we are using the [`sphinx-reredirects`](https://documatt.com/sphinx-reredirects/usage/) plugin.
+
+When moving a page, add a redirect from the old location to the new location. When deleting a page, add a redirect to
+the most suitable alternative documentation. The redirects are configured by the `redirects` key in `doc/conf.py`.

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/compiling/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,114 @@
+# 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:
+- Download a recent Eclipse version directly from
+[the eclipse website](https://www.eclipse.org/downloads/packages/); choose the package for "RCP and RAP developers"
+- Use the most recent version in `\\isis\inst$\Kits$\CompGroup\ICP\Developer Tools` (which is simply a download from
+the Eclipse website, at a specific version).
+
+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
+
+:::{seealso}
+If at any point during these instructions you get errors, there are troubleshooting notes for Eclipse
+[here](../eclipse/Common-Eclipse-Issues) and for the GUI in general [here](../GUI-Troubleshooting).
+:::
+
+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; 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, then click "Apply" 
+and select "Run".
+
+Lastly, you should [set up checkstyle](../eclipse/Checkstyle-setup).
+
+{#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

@@ -0,0 +1,135 @@
+# Maven and Tycho
+
+The IBEX GUI is built using Tycho, which is a Maven plugin used for building Eclipse RCP products.
+
+This document provides a brief overview of both Maven and Tycho.
+
+:::{seealso}
+[Code chats](/processes/meetings/Code-Chats-and-Lightning-Talks) have been given on this topic (
+[slides](https://stfc365.sharepoint.com/:p:/r/sites/ISISExperimentControls/ICP%20Discussions/GUI_Chat_Slides/IBEX%20GUI%20build%20system.pptx?d=w74aa3046025f4622bcdeadbdeca9395c&csf=1&web=1&e=aQEGJZ),
+[recording](https://stfc365.sharepoint.com/sites/ISISExperimentControls/_layouts/15/stream.aspx?id=%2Fsites%2FISISExperimentControls%2FICP%20Discussions%2FGUI%5FChat%5FSlides%2FIBEX%20GUI%20build%20System%20Code%20chat%2Emp4&referrer=StreamWebApp%2EWeb&referrerScenario=AddressBarCopied%2Eview&referrer=StreamWebApp%2EWeb&referrerScenario=AddressBarCopied%2Eview%2E0f53ae8b%2D3184%2D43c1%2D955e%2D039109fcd0e1)
+).
+:::
+
+## 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._
+
+In simple terms, Maven is a build automation tool used primarily for Java projects.
+
+See the [getting started guide in the Maven documentation](https://maven.apache.org/guides/getting-started/index.html)
+for more information about what Maven is.
+
+### POM files
+
+POM files are XML files, called `pom.xml`, that describes the software project being built, its dependencies on other
+external modules and components, the build order, directories, and required plug-ins. In many ways, it can be considered
+the equivalent of a C-style Makefile as it defines how the project is built.
+
+See [the Maven documentation](https://maven.apache.org/pom.html) for detailed information on the various sections of a
+`pom.xml` in a pure Maven project.
+
+### Building a Maven project
+
+Maven uses multiple build phases - for example, `compile`, `test`, `package`. If you are really unsure, a good
+default is to run `mvn clean verify` to build a project; this will clean the project (deleting any old build files),
+and then run compilation, unit tests, packaging, and verification (e.g. checkstyle) phases.
+
+For more information, see the Maven
+[build lifecycle documentation](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html).
+
+## Tycho
+
+Tycho is a set of Maven plugins and extensions for building Eclipse-based applications with Maven. Tycho allows Maven
+to support building bundles, fragments, features, P2 repositories, RCP applications etc.
+
+Tycho is used to build the IBEX GUI application.
+
+### Parent POM
+
+Maven allows a parent POM to be defined which contains references to the other POM files for the other projects that
+make up an application. This is used in the IBEX GUI because it allows the centralisation of the settings for
+building the application.
+
+The [IBEX GUI parent `pom.xml`](https://github.com/ISISComputingGroup/ibex_gui/blob/master/base/uk.ac.stfc.isis.ibex.client.tycho.parent/pom.xml)
+contains a lot of information, so here is a stripped down version to show the key points:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>CSS_ISIS</groupId>
+    <artifactId>uk.ac.stfc.isis.ibex.client.tycho.parent</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <packaging>pom</packaging>
+
+    <properties>
+        <tycho.version>4.0.9</tycho.version>
+        <tycho-repo.url>https://oss.sonatype.org/content/groups/public/</tycho-repo.url>
+        <photon-repo.url>http://download.eclipse.org/releases/2024-09</photon-repo.url>
+        <photon-updates-repo.url>http://download.eclipse.org/eclipse/updates/4.33</photon-updates-repo.url>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <repositories>
+        <repository>
+            <id>photon-updates</id>
+            <layout>p2</layout>
+            <url>${photon-updates-repo.url}</url>
+        </repository>
+    </repositories>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.eclipse.tycho</groupId>
+                <artifactId>tycho-maven-plugin</artifactId>
+                <version>${tycho.version}</version>
+                <extensions>true</extensions>
+            </plugin>
+            <!-- Other maven plugins omitted such as unit testing and checkstyle -->
+        </plugins>
+    </build>
+
+    <modules>
+        <module>../uk.ac.stfc.isis.ibex.client.product</module>
+        <module>../uk.ac.stfc.isis.ibex.feature.base</module>
+        <!-- Other modules that make up IBEX would be listed here -->
+        <module>../uk.ac.stfc.isis.ibex.ui.mainmenu.tests</module>
+    </modules>
+</project>
+```
+
+Let's explain the various parts shown:
+* At the top we have the standard Maven metadata: `groupId`, `artifactId`, `version`.
+* The properties section is used to define URLs for the Tycho plugin and the Eclipse RCP framework. The versions here
+are updated periodically during [dependency updates](/processes/dev_processes/Dependency-Updates)
+* The repositories section tells Maven to look for a repository for the Eclipse RCP framework version specified above
+* The build section defines the Maven plugins necessary to build the application. The Tycho plugin entry tells Maven to
+download Tycho and use it as part of the build process
+* The modules section lists the locations of the POM files for the various modules that make up the application. When a
+new module is added to IBEX, it will need to be added to this list.
+
+### Child POM
+
+A typical child POM look like
+[this](https://github.com/ISISComputingGroup/ibex_gui/blob/master/base/uk.ac.stfc.isis.ibex.dashboard/pom.xml).
+It is very simple - it points at the parent POM to get most of its information. These is one of these `pom.xml` files
+for each module that makes up the IBEX client.
+
+The packaging type is defined as `eclipse-plugin`; this is a packaging type defined by Tycho. Other Tycho types used in
+IBEX are `eclipse-feature` for features, `eclipse-test-plugin` for fragment projects that define unit tests and
+`eclipse-repository` for configuring builds.
+
+### Application POM
+
+In IBEX we define a separate project called `uk.ac.stfc.isis.ibex.e4.client.product` which defines how the product is 
+built. It has a 
+[POM file](https://github.com/ISISComputingGroup/ibex_gui/blob/master/base/uk.ac.stfc.isis.ibex.e4.client.product/pom.xml)
+of packaging type `eclipse-repository`.
+
+The key area is the `materialize-products` section, this tells Tycho to actually create the product. Without this Maven
+will compile & unit test the code, but will not produce an executable.