diff --git a/doc/Client.md b/doc/Client.md index 4b19fb14e..12c2a61af 100644 --- a/doc/Client.md +++ b/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 diff --git a/doc/Editing-the-Wiki.md b/doc/Editing-the-Wiki.md index 03e2dd0d3..9e159b181 100644 --- a/doc/Editing-the-Wiki.md +++ b/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`. diff --git a/doc/Script-Generator.md b/doc/Script-Generator.md index 88279c0b0..4370cc659 100644 --- a/doc/Script-Generator.md +++ b/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 diff --git a/doc/client/GUI-Building.md b/doc/client/GUI-Building.md new file mode 100644 index 000000000..2c41713d8 --- /dev/null +++ b/doc/client/GUI-Building.md @@ -0,0 +1,8 @@ +# Building + +```{toctree} +:glob: +:titlesonly: + +compiling/* +``` diff --git a/doc/client/GUI-Getting-Started.md b/doc/client/GUI-Getting-Started.md deleted file mode 100644 index 229a8a4a4..000000000 --- a/doc/client/GUI-Getting-Started.md +++ /dev/null @@ -1,8 +0,0 @@ -# Getting Started - -```{toctree} -:glob: -:titlesonly: - -getting_started/* -``` \ No newline at end of file diff --git a/doc/client/GUI-Troubleshooting.md b/doc/client/GUI-Troubleshooting.md index cde5d4f32..75737e333 100644 --- a/doc/client/GUI-Troubleshooting.md +++ b/doc/client/GUI-Troubleshooting.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: diff --git a/doc/client/compiling/Building-the-GUI.md b/doc/client/compiling/Building-the-GUI.md new file mode 100644 index 000000000..abc13d20a --- /dev/null +++ b/doc/client/compiling/Building-the-GUI.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. +::: + + + +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: + + + +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". + + + +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\`. diff --git a/doc/client/compiling/Maven-and-Tycho.md b/doc/client/compiling/Maven-and-Tycho.md new file mode 100644 index 000000000..5410db874 --- /dev/null +++ b/doc/client/compiling/Maven-and-Tycho.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 + + 4.0.0 + CSS_ISIS + uk.ac.stfc.isis.ibex.client.tycho.parent + 1.0.0-SNAPSHOT + pom + + + 4.0.9 + https://oss.sonatype.org/content/groups/public/ + http://download.eclipse.org/releases/2024-09 + http://download.eclipse.org/eclipse/updates/4.33 + UTF-8 + + + + + photon-updates + p2 + ${photon-updates-repo.url} + + + + + + + org.eclipse.tycho + tycho-maven-plugin + ${tycho.version} + true + + + + + + + ../uk.ac.stfc.isis.ibex.client.product + ../uk.ac.stfc.isis.ibex.feature.base + + ../uk.ac.stfc.isis.ibex.ui.mainmenu.tests + + +``` + +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. diff --git a/doc/client/compiling/eclipse_clear_workspace.png b/doc/client/compiling/eclipse_clear_workspace.png new file mode 100644 index 000000000..c80e68c15 Binary files /dev/null and b/doc/client/compiling/eclipse_clear_workspace.png differ diff --git a/doc/client/compiling/eclipse_import_ibex_gui.png b/doc/client/compiling/eclipse_import_ibex_gui.png new file mode 100644 index 000000000..9f9273b53 Binary files /dev/null and b/doc/client/compiling/eclipse_import_ibex_gui.png differ diff --git a/doc/client/compiling/eclipse_target_platform_view.png b/doc/client/compiling/eclipse_target_platform_view.png new file mode 100644 index 000000000..ddbac8dd7 Binary files /dev/null and b/doc/client/compiling/eclipse_target_platform_view.png differ diff --git a/doc/client/compiling/eclipse_workspace_selection.png b/doc/client/compiling/eclipse_workspace_selection.png new file mode 100644 index 000000000..f815159d6 Binary files /dev/null and b/doc/client/compiling/eclipse_workspace_selection.png differ diff --git a/doc/client/eclipse/Common-Eclipse-Issues.md b/doc/client/eclipse/Common-Eclipse-Issues.md index d89637e61..c2136b5a4 100644 --- a/doc/client/eclipse/Common-Eclipse-Issues.md +++ b/doc/client/eclipse/Common-Eclipse-Issues.md @@ -4,7 +4,8 @@ Sometimes the error messages that Eclipse gives are a little opaque, so here are ## Plugin execution not covered by lifecycle configuration -Go to window -> preferences -> Maven -> Errors/Warnings. Change "Plugin execution not covered by lifecycle configuration" to ignore in the drop down. +Go to window -> preferences -> Maven -> Errors/Warnings. +Change "Plugin execution not covered by lifecycle configuration" to ignore in the drop down. ## The type XXXXXXX cannot be resolved. It is indirectly referenced from required .class files @@ -122,8 +123,25 @@ Sometimes when you check out a new branch in the ibex GUI repository, you won't 1. In Eclipse, remove all the projects from the workspace and close Eclipse. 1. Then, while checked out to the branch you want to see the changes on, perform a `git clean -fdx && git reset HEAD --hard` to reset the git repository. This will remove any changes you have made to the branch. -1. Restart Eclipse and repeat the steps to get the GUI working from [Building the GUI](../getting_started/Building-the-GUI). +1. Restart Eclipse and repeat the steps to get the GUI working from [Building the GUI](../compiling/Building-the-GUI). ## Build fails with `[ERROR] Failed to resolve target definition ... targetplatform.target: Could not find "org.eclipse.e4.tools.spies.feature.feature.group..." in the repositories of the current location` This probably means that our pinned target has gone out of date and needs updating. Open the Eclipse IDE and click on `org.eclipse.tools/latest` and click `update` this should fail and show `Unable to locate installable unit ...`. To fix this remove the plugin and then add it from the `software site `, work with `org.eclipse.e4.core.tools.update - http://download.eclipse.org/e4/snapshots/org.eclipse.e4.tools/latest` then you add `Eclipse E4 - All Spies`. + +## Validation error in target platform `jython` manifests + +Make sure that `-Djdk.util.zip.disableZip64ExtraFieldValidation=true` is included in `eclipse.ini` (located right next +to the `eclipse.exe` executable). + +## `java.lang.UnsupportedClassVersionError` + +If you see a `java.lang.UnsupportedClassVersionError` error at runtime, then: +- Select Window -> Preferences -> Java -> Compiler +- Set compliance level to 21. + +## Adding a dictionary to Eclipse's spelling checker + +- In Eclipse open `Window > Preferences > General > Editors > Text Editors > Spelling` +- Change the "User defined dictionary" to `/Eclipse settings/code_dictionary.txt` + diff --git a/doc/client/eclipse/Common-Eclipse-Tasks.md b/doc/client/eclipse/Common-Eclipse-Tasks.md index aeb62df24..1d8596191 100644 --- a/doc/client/eclipse/Common-Eclipse-Tasks.md +++ b/doc/client/eclipse/Common-Eclipse-Tasks.md @@ -127,8 +127,7 @@ public class FooDisplay extends Canvas Instructions on adding a new perspective can be found [here](../coding/Adding-a-Button-to-the-Perspective-Switcher). -Add A Preference Page ---------------------- +## Add A Preference Page Many plugins may have options that you want the user of the client to be able to configure. The simplest way to achieve this is to have the plugin contribute a preference page to the client's preference window. @@ -296,7 +295,3 @@ The ``plugin.xml`` should now resemble: ``` The menu should now be visible in the client UI. For more details see the [Vogella menus tutorial](http://www.vogella.com/tutorials/EclipseCommands/article.html). - -## Add A Third Party Library To A Plugin - -To do \ No newline at end of file diff --git a/doc/client/eclipse/Creating-the-IBEX-Developer-Version-of-Eclipse.md b/doc/client/eclipse/Creating-the-IBEX-Developer-Version-of-Eclipse.md deleted file mode 100644 index a11029cf4..000000000 --- a/doc/client/eclipse/Creating-the-IBEX-Developer-Version-of-Eclipse.md +++ /dev/null @@ -1,3 +0,0 @@ -# Creating the IBEX developer version of Eclipse - -The recommended IBEX developer version of Eclipse can be found at `\\isis\inst$\Kits$\CompGroup\ICP\Developer Tools`. diff --git a/doc/client/eclipse/Dictionary-setup.md b/doc/client/eclipse/Dictionary-setup.md deleted file mode 100644 index ad471db59..000000000 --- a/doc/client/eclipse/Dictionary-setup.md +++ /dev/null @@ -1,9 +0,0 @@ -# Dictionary setup - -Spelling error highlights fix - -1. In Eclipse open `Window > Preferences > General > Editors > Text Editors > Spelling` -1. Change the "User defined dictionary" to `/code_dictionary.txt` - - - diff --git a/doc/client/getting_started/Building-the-GUI.md b/doc/client/getting_started/Building-the-GUI.md deleted file mode 100644 index 812d4c90b..000000000 --- a/doc/client/getting_started/Building-the-GUI.md +++ /dev/null @@ -1,94 +0,0 @@ -# Building the GUI - -Before building and running the GUI please make sure you have followed the steps from here: [First time installing and building (Windows)](/overview/First-Time-Build). In particular make sure Git and genie_python are installed. - -## Eclipse RCP resources - -We have a book which should serve as a reasonable introduction to the Eclipse RCP platform: 'Eclipse Rich Client Platform' by McAffer, Lemieux and Aniszczyk. There is also a basic introduction at http://www.vogella.com/tutorials/EclipseRCP/article.html. - -## Checking out the GUI - -Create a directory for where you want your IBEX GUI to reside (e.g. `C:\Instrument\Dev`). From an appropriate Git console (e.g. Git Bash) navigate to your directory and run: - -`git clone https://github.com/ISISComputingGroup/ibex_gui.git` - -## Building via Eclipse ## - -### Eclipse - -You must use a version of eclipse >= 2019-06, earlier versions will fail to build the client. An appropriate version is available at `\\isis\inst$\Kits$\CompGroup\ICP\Developer Tools`, simply unzip the the latest version folder to your chosen location for Eclipse (e.g. `C:\Tools\eclipse`) and use the provided workspace. - -You can choose to download Eclipse directly from [the eclipse website](http://www.eclipse.org/downloads/packages/), choose the package for "RCP and RAP developers". If you choose to download eclipse directly from the eclipse website, and you get errors about failing to resolve `jython` manifests, you will need to add `-Djdk.util.zip.disableZip64ExtraFieldValidation=true` to `eclipse.ini` (located right next to the eclipse.exe executable). - -### Building - -These are the steps needed to run the GUI via Eclipse: - -1. First, create a new workspace (example name: ibex_workspace_E4). -1. Then `git checkout master` from where the IBEX code was cloned to (if it's a fresh clone, it should already be on this branch). -1. Install the [pre-commit hook](https://github.com/ISISComputingGroup/IBEX/issues/4786). To install this hook you must run `install_pre_commit_hook.bat` from the `\build` subdirectory. -1. Start Eclipse IDE and select the workspace and use "Browse" to create and select the new workspace folder. -1. From the menu bar choose File->Import->General->Existing Projects into Workspace. Choose "Select root directory" and browse to `\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. If a "Marketplace solutions available" dialogue appears, click cancel as these will be obtained later. -1. If there is a "Welcome" tab open in Eclipse, close it. 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 target file and choose "Set as Active Target Platform". This may take some time as parts of CS-Studio and DAWN are downloaded. It may also be required to update the Locations in use should some packages appear to be missing. -1. Then select Project->Clean from the menu bar. -1. 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". -1. Next, From the menu bar choose Run->Run configurations and select "ibex.product" from the left hand list under "Eclipse Application". -1. In the "Main" tab in **Run configurations** tick the "Clear" tick box and untick the "Ask for confirmation before clearing". In the "Configuration" tab tick the "Clear the configuration area before launching" tick box. Click "Apply" and select "Run". - -Note: If there is a `ava.lang.UnsupportedClassVersionError` error then go to Window -> Preferences -> Java -> Compiler -> Set compliance level to 21 - -IBEX should now build but there will probably be some errors. You can clear them following the procedure below. - -**Important Notes:** -* you will need JDK 21 installed to launch the IBEX GUI successfully. -* you should also [set up the checkstyle](../eclipse/Checkstyle-setup), do it sooner than later as it may prevent potential errors - -### If you see a “Plugin execution not covered by lifecycle configuration” error -1. From the menu bar choose: Window->Preferences -1. Expand Maven and choose Errors/Warnings -1. Set "Plugin execution not covered by lifecycle configuration" to Warning or Ignore - -### Configuring Eclipse to show current Git repository and branch in the Package Explorer - -e.g. `uk.ac.stfc.isis.ibex.targetplatform [ibex_gui_e4 master]` - -Not for new starters: this should already have been done by eclipse so unless you do not see `[ibex_gui_e4 master]` next to the name of a plugin/package you do not need to do any of the following. -1. Select all plugins (ctrl-a) -1. Right-click on any one plugin and select `Team -> Share Project` -1. Click `Finish` -1. The repository and branch names should now be displayed after each plugin as above - - -## Building via Maven ## - -1. Ensure your maven version is >= 3.6.0, excluding 3.6.1 as that version has a bug -1. Double check that your maven is the correct version by running `mvn -v` in a new command window. Older versions will give you very hard to diagnose build errors -1. From the command line, navigate to the `.\build\` directory in the IBEX code (one directory under the root, which should be `ibex_gui\`). -1. Run `build.bat` -1. Wait for a few minutes while it builds -1. After the build finishes it can be found in `.\built_client\` - -## Troubleshooting ## - -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. - -Errors can occur if the wrong version of Java is installed for your OS. For example, the `x86` version can differ from the `x64` version and can cause issues when building the GUI. - -## Eclipse troubleshooting ## - -Sometimes eclipse will tell you that you have errors when you open it. The following operations (may) help. -- Refresh, clean and build all projects. Select all projects, press F5 to refresh, then go to `Project -> Clean` to clean all projects. -- Go to `Run -> Run Configurations -> Plugins` and press "Add required plugins". You can now validate/apply your choice. -- In `uk.ac.stfc.isis.ibex.targetplatform`, open `uk.ac.stfc.isis.ibex.targetplatform.target` and click "set as target platform". -- If you have done all these steps and it still doesn't work, there is more troubleshooting information [here](../eclipse/Common-Eclipse-Issues). -- If all else fails, delete all the projects from eclipse's workspace and reimport them. - -Eclipse can automatically set the Java standard for some projects to `1.8`. If you are seeing errors such as `var cannot be assigned to a type` on certain projects, navigate to the project in the explorer, then right-click and choose Properties->Java Compiler->Configure Workspace Settings, and then set the required Java standard to `11`. - -If you have a lot of errors make sure that `-Djdk.util.zip.disableZip64ExtraFieldValidation=true` is included in `eclipse.ini` (located right next to the eclipse.exe executable). - -## Further Troubleshooting ## - -Additional support can be found [here](../GUI-Troubleshooting). diff --git a/doc/client/getting_started/GUI-Development-Workflow.md b/doc/client/getting_started/GUI-Development-Workflow.md deleted file mode 100644 index cd436b51f..000000000 --- a/doc/client/getting_started/GUI-Development-Workflow.md +++ /dev/null @@ -1,348 +0,0 @@ -# Development workflow - -## Quick overview of workflow - -1. **Create a branch for the ticket (based on master) via GitHub (developer)** - * Use the git issue number for the branch name followed by a brief description, e.g. Ticket780_SelectNewTarget -1. **Clone the branch locally (developer)** -1. **Modify the code (developer)** - * Update any copyright notices to the current year to read ``Copyright (C) - ...`` -1. **Push back the changes (developer)** - * Make sure you have merged in any changes to master that have occurred since your ticket was created - makes reviewer's life easier - * Please follow commenting guidelines below -1. **Create a pull request (developer)** - * Reference the git issue in the comments, for example: ```ISISComputingGroup/IBEX/issues/1016``` - * Assign the correct milestone - * Add a record of the changes to [Release Notes](https://github.com/ISISComputingGroup/IBEX/wiki/ReleaseNotes_Dev) under "Changes in software but still on a branch" -1. **Review (reviewer)** - * Assign the pull request to yourself to indicate you are reviewing it and label`under review` - * Check that the pull request has been built by Jenkins with no errors (if there is a Jenkins build) - * Check that the ticket fixes the associated issue - * If it is okay then move to the next step, otherwise inform the developer of the problem and add a comment to the pull request -1. **Merge the changes (reviewer or developer)** - * If it is a simple merge the reviewer can do it, otherwise ask the developer to do it - * Move the relevant entry in the [Release Notes](https://github.com/ISISComputingGroup/IBEX/wiki/ReleaseNotes_Dev) from "Changes in software but still on a branch" to "Changes merged into master" -1. **Delete the branch (reviewer or developer)** -1. **Close the ticket in Trac (reviewer or developer)** - -Notes: - -* You don't have to create branches on GitHub first, often it is more convenient to create them locally first instead (which you must do if you intend to rebase) -* Deleting a branch on github does not delete it from you local repository clone - -## Cloning the repository (first time only) - -* From the repository page copy the "HTTPS clone URL": - -![GitHub](clone.png) - -* Open Git Bash or Git Shell from the Windows Start Menu - -* In the console enter the following (paste the address from the previous step) to create a local copy of the repository: - -``` -user@MACHINE /c/Instrument/Dev/ (master) -$ git clone https://github.com/ISISComputingGroup/ibex_gui.git -``` - -* Now enter the ibex_gui directory: -``` -user@MACHINE /c/Instrument/Dev/ibex_gui/base (master) -$ cd ibex_gui -``` -* The command line shows in brackets which branch you are on - probably master at this time - -* Use the git branch command to list the available branches: - -``` -user@MACHINE /c/Instrument/Dev/ibex_gui/base (master) -$ git branch -a -* master - remotes/origin/HEAD -> origin/master - remotes/origin/master -``` - -* In the console enter `git checkout master` to change to a working copy of the E4 (latest) revision of the GUI - -``` -user@MACHINE /c/Instrument/Dev/ibex_gui/base (master) -$ git checkout master -Checking out files: 100% (994/994), done. -Switched to a new branch 'master' -Branch 'master' set up to track remote branch 'master' from 'origin'. -``` - -* The branch name in brackets after the working directory should change to `master`: -``` -user@MACHINE /c/Instrument/Dev/ibex_gui/base (master) -$ -``` -## Creating a branch - -* Go to the IBEX GUI GitHub repository https://github.com/ISISComputingGroup/ibex_gui -* The page should look something like this: - -![GitHub](start.png) - -* Click the branch drop-down button which will list all the current branches. Type a name in the box and then click "Create branch" to create a new branch: - -![GitHub](create_branch.png) - -Note: Use the Trac ticket number for the branch name followed by a brief description, e.g. Ticket780_SelectNewTarget - -* The page should switch to the new branch: - -![GitHub](new_branch.png) - -## Cloning the branch locally - -It is necessary to clone the new branch locally if you don't already have it: - -* First get an updated list of remote branches: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master) -$ git remote update -Fetching origin -From https://github.com/ISISComputingGroup/ibex_gui - * [new branch] Ticket768 -> origin/Ticket768 -``` -* The new branch should appear in the branch list: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master) -$ git branch -a -* master - remotes/origin/HEAD -> origin/master - remotes/origin/Ticket768 - remotes/origin/master -``` -* Switch to the new branch created earlier: -``` -$ git checkout Ticket768 -``` -* Now you can start coding! - -## Pushing the changes back - -Now the code changes have been made, it is time to push the changes back to the repository on GitHub: - -* From the command line we can see what changes we have made using the git status command like so: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (Ticket768) -$ git status -s - M uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/BannerComposite.java - M uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/GroupsPanel.java -?? .metadata/ -?? uk.ac.stfc.isis.ibex.client.tycho.parent/workspace/ -?? workspace/ -?? ../runtime-ibex.product/ -?? ../surefire-reports/ -``` - -We can see that I have modified two .java files (indicated by the M) and there are a few files not under source control (indicated by ??). -I am not interested in the files not under source control as they are default files created by Eclipse. Notice that there is a space before the M on the modified files. - -* To be able to commit the changes back they have to be staged using the git add command like so: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (Ticket768) -$ git add -u -``` - -The -u flag tells git to stage any modified files that are already in source control. To add new files or stage only specific files use the file name instead like so: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (Ticket768) -$ git add some_file_name.txt -``` -* If we repeat the git status command we get something like this: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (Ticket768) -$ git status -s -M uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/BannerComposite.java -M uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/GroupsPanel.java -?? .metadata/ -?? uk.ac.stfc.isis.ibex.client.tycho.parent/workspace/ -?? workspace/ -?? ../runtime-ibex.product/ -?? ../surefire-reports/ -``` -Notice that there is no longer a space before the M, this indicates that the file is staged. - -* Now we commit the changes locally using the git commit command. - -The commit will require a comment and the format for comments should be as per https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message i.e. -50 char title, blank line, further details wrapped at 72 characters per line. -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (Ticket768) -$ git commit -``` -* Check for upstream commits - -Before we finally push to the server we will merge into our branch any changes that have been pushed to master on github, this -is to make the job easier for a reviewer as we will see potential merge conflicts and handle them ourselves. We update our local master branch with -changes on GitHub and then merge them into our copy: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (Ticket768) -$ git pull origin master -From https://github.com/ISISComputingGroup/ibex_gui - * branch master -> FETCH_HEAD - Already up-to-date. -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (Ticket768) -$ git merge master -Already up-to-date. -``` -(Advanced usage note: if your branch does not yet exist on GitHub, and has not been otherwise shared with another developer, then you may wish to consider doing a rebase rather than a merge) - -* Next we push the changes back to GitHub using the git push command like so: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (Ticket768) -$ git push origin Ticket768 -Counting objects: 31, done. -Delta compression using up to 8 threads. -Compressing objects: 100% (8/8), done. -Writing objects: 100% (15/15), 965 bytes | 0 bytes/s, done. -Total 15 (delta 6), reused 0 (delta 0) -To https://github.com/ISISComputingGroup/ibex_gui.git - 86f5162..8b9814f Ticket768 -> Ticket768 -``` -* If we navigate back to the branch on the GitHub page we can see that the changes have been pushed back: - -![GitHub](pushed_branch.png) - -## Create a pull request - -* Create a pull request by clicking the 'Compare & pull request' button while on the correct branch: - -![GitHub](pull_request_start.png) - -* The new page allows you to add comments and to review the modifications before creating the pull request. -Notice that for my changes it says "Able to merge". This means that my changes don't clash with any other changes that have been made on the master while I have been working on the branch. - -![GitHub](open_a_pull_request.png) - -* Clicking the "Create pull request" button will create the pull request - -* Reference the git issue in the comments by paste a link to the issue. For example ```ISISComputingGroup/IBEX/issues/1016``` - -* Assign the correct milestone - -* Ensure that the code has built and tested correctly, this can be seen by a message on the bottom of the PR. Note that any increase in checkstyle issues will result in a failed build. If you believe these to be unavoidable discuss with the reviewer. - -![GitHub](checked_pr.png) - -* That is us done for now as the ticket now needs to be reviewed -* Add a summary of your changes to the table under "Changes in software but still on a branch" in the [Release Notes](https://github.com/ISISComputingGroup/IBEX/wiki/ReleaseNotes_Dev). If your changes require modifications to files on some or all of the instruments to work correctly, document these in the relevant section. - -## Reviewing a pull request - -Before reviewing the pull request it is necessary to copy the branch locally if you don't already have it: - -* First get an updated list of remote branches: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master) -$ git remote update -Fetching origin -From https://github.com/ISISComputingGroup/ibex_gui - * [new branch] Ticket768 -> origin/Ticket768 -``` -* The new branch should appear in the branch list: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master) -$ git branch -a -* master - remotes/origin/HEAD -> origin/master - remotes/origin/Ticket768 - remotes/origin/master -``` -* Now checkout the branch: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master) -$ git checkout Ticket768 -Branch Ticket768 set up to track remote branch Ticket768 from origin. -Switched to a new branch 'Ticket768' -``` - -* The code can now be loaded into Eclipse and reviewed - -* Once the code has been reviewed either you can merge the changes yourself via GitHub or you can pass it back to the developer to do it - -## Merging changes - -Basically there are two types of merges: one where the code changes don't clash with other changes on master; and, one where it does clash. - -If it does not clash then it can be merged via the "Merge pull request" button on the pull request page on GitHub. - -Otherwise, GitHub will say "We can't automatically merge this pull request" on the pull request page. -This requires manual intervention: - -* From the command line switch to the the master branch if not already on it - -* Next fetch the most up-to-date version of master: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master) -$ git fetch origin - -* Merge the master with the branch: - -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master) -$ git merge Ticket768 -Auto-merging base/uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/GroupsPanel.java -CONFLICT (content): Merge conflict in base/uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/GroupsPanel.java -Automatic merge failed; fix conflicts and then commit the result. -``` -* The merge has failed (as expected) but we can now view the code conflict in Eclipse: -```java -... -<<<<<<< HEAD - showBanner("No groups to display!"); -======= - // Leave text blank - showBanner(""); ->>>>>>> Ticket768 -... -``` - -* For this example I decide to keep my changes and ignore the master, so the next step is merge the new changes and update on GitHub: -``` -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master|MERGING) -$ git status -s -M uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/BannerComposite.java -UU uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/GroupsPanel.java -?? .metadata/ -?? uk.ac.stfc.isis.ibex.client.tycho.parent/workspace/ -?? workspace/ -?? ../runtime-ibex.product/ -?? ../surefire-reports/ - -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master|MERGING) -$ git add uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/GroupsPanel.java - -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master|MERGING) -$ git status -s -M uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/BannerComposite.java -M uk.ac.stfc.isis.ibex.ui.blocks/src/uk/ac/stfc/isis/ibex/ui/blocks/groups/GroupsPanel.java -?? .metadata/ -?? uk.ac.stfc.isis.ibex.client.tycho.parent/workspace/ -?? workspace/ -?? ../runtime-ibex.product/ -?? ../surefire-reports/ - -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master|MERGING) -$ git commit -m "Resolved conflict with Ticket768" -[master 2aaaf10] Resolved conflict with Ticket768 - -mjc23@NDW1373 /c/CodeWorkspaces/GitHub/ibex_gui/base (master) -$ git push origin master -Username for 'https://github.com': matt.clarke@stfc.ac.uk -Password for 'https://matt.clarke@stfc.ac.uk@github.com': -Counting objects: 1, done. -Writing objects: 100% (1/1), 229 bytes | 0 bytes/s, done. -Total 1 (delta 0), reused 0 (delta 0) -To https://github.com/ISISComputingGroup/ibex_gui.git - 06cecee..2aaaf10 master -> master -``` -* Now if you look at the pull request on GitHub it should say it has been merged and closed. -* Move the changes documented in the [Release Notes](https://github.com/ISISComputingGroup/IBEX/wiki/ReleaseNotes_Dev) down into the table in the "Changes merged into master" section, as well as any required instrument-specific modifications related to the same ticket. - -## Deleting the branch - -Once the branch has been merged into master it can be deleted via the pull request page on GitHub. Don't worry it is not permanently deleted! -You will also have to delete the branch locally. \ No newline at end of file diff --git a/doc/client/getting_started/Maven-and-Tycho.md b/doc/client/getting_started/Maven-and-Tycho.md deleted file mode 100644 index 1510d0080..000000000 --- a/doc/client/getting_started/Maven-and-Tycho.md +++ /dev/null @@ -1,368 +0,0 @@ -# Maven and Tycho - -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._ - -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. - -In many ways it can be consider the equivalent of a C-style Makefile as it defines how the project is built. Here is an example: - -```xml - - - - 4.0.0 - com.maven_example.test - test - 1.0-SNAPSHOT - jar - - - - junit - junit - 4.8.2 - test - - - - - UTF-8 - - - - - - org.sonatype.install4j - install4j-maven-plugin - - - compile-installers - package - - compile - - - ${project.basedir}/src/main/installer/myproject.install4j - - - - - - - - -``` - -Let's explain the various parts shown: -* Near the top we have the following information: - * The `groupId` is usually the name of the overarching project and is the same style as a Java package ID, e.g. org.apache.maven - * The name that the project is often known by, e.g. maven - * The version number. SNAPSHOT is automatically replaced by a date-time indicating the build time - * Packaging defines what is built, in this case a standard jar file -* The dependencies section defines any external dependencies required for the project, in this case only junit is required -* The properties section is used to define other properties relevant to the build -* The build section defines specific information for the build such as the plugins to use. In this example, we use install4j to create an executable file - -See https://maven.apache.org/pom.html for more information on the various sections. - -### A Maven project ### - -Maven is very picky about how a project is laid out, it requires the various directories to be named and positioned correctly. -Luckily, most IDEs will take care of this for us. - -The layout is as follows: -``` -|- The top-level of the project - |- src - |- main - |- java - |- The packages directories for the source e.g. com.myexample - |- resources - |- test - |- java - |- The packages directories for the tests - - pom.xml -``` - - -The POM described above is sufficient for us to build a project from the command line using Maven. The commonly used commands used are: - -* `mvn compile` - this creates the JVM bytecode -* `mvn test` - this runs any unit tests -* `mvn package` - create the jar and runs the tests -* `mvn clean` - removes any previous build artifacts - -### Multiple modules ### - -If we have a project made up of a number of different packages (or modules) with dependencies then Maven can handle that. -For example, let's say we have two separate packages: com.example.library; and, com.example.application where application depends on library. The POM for application would need to indicate this dependency like so: - -```xml - - - - 4.0.0 - com.maven_example - myApp - 1.0-SNAPSHOT - jar - - - - com.example.library - library - 1.0-SNAPSHOT - compile - - - com.google.code.gson - gson - 2.6.2 - compile - - - -``` -It also has a dependency on GSON for the hell of it. The dependencies have a scope, this determines how they are treated. The most common options are: - -* `compile` - dependencies are available in all classpaths (default) -* `test` - only needed for testing -* `provided` - provided at run-time, e.g. from the JDK -* `runtime` - not needed for compilation -* `system` - have to provide the containing JAR explicitly - -There are other options and more detailed explanations on the [Maven website] (https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html) - -Now application has no idea where to find library, so we create a new POM file in a higher directory which will be our parent POM. The parent provides the information for both modules to work together. The POM looks something like: - -```xml - - - - 4.0.0 - com.example.parent - parent - 1.0-SNAPSHOT - pom - - - com.example.application - com.example.library - - -``` -The modules tags specify the location of the modules to build. And the modules' POMs need to have a reference to the parent, like so: - -```xml - - - - 4.0.0 - com.example - library - 1.0-SNAPSHOT - jar - - - com.example.parent - parent - 1.0-SNAPSHOT - - -``` -Running the build using the parent POM (i.e. from the same directory) will build both modules and link them appropriately. - -### Profiles ### -Using profiles it is possible to configure the build for different circumstances. For example, say I want to install the final product in a certain directory sometimes then I can add a profile for this, like so: - -```xml - - - - 4.0.0 - com.example - library - 1.0-SNAPSHOT - jar - - - com.example.parent - parent - 1.0-SNAPSHOT - - - - - release - - c:\\release\ - - - - -``` -Running the build with the profile specified will result in the final product being installed into the specified directory. To run a profile, specify the profile using -P like so: -```mvn package -Prelease``` - -Profiles can be used for a number of things, such as specifying the JDK version number or the OS to build for. - -For more information see the [Maven website] (http://maven.apache.org/guides/introduction/introduction-to-profiles.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 that is deployed on the instruments. - -### The 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 POM contains a lot of information, so here is a stripped down version to show the key points. - -```xml - - 4.0.0 - CSS_ISIS - uk.ac.stfc.isis.ibex.client.tycho.parent - 1.0.0-SNAPSHOT - pom - - - 0.20.0 - https://oss.sonatype.org/content/groups/public/ - http://download.eclipse.org/releases/kepler - http://download.eclipse.org/eclipse/updates/3.8 - UTF-8 - - - - - kepler-updates - p2 - ${kepler-updates-repo.url} - - - - - - - org.eclipse.tycho - tycho-maven-plugin - ${tycho.version} - true - - - - - - - - ../uk.ac.stfc.isis.ibex.client.product - ../uk.ac.stfc.isis.ibex.feature.base - - - - ../uk.ac.stfc.isis.ibex.ui.mainmenu.tests - - - -``` -Let's explain the various parts shown: -* At the top we have the standard Maven boiler plate as discussed above -* The properties section is used to define properties relevant to the build, in this case, the URLs for the various repositories we are using -* The repositories section defined the version of Eclipse we are building against. -* The build section defines the plugins that will be used to build the application. Most of the ones we used have been removed for clarity. The Tycho plugin entry tells Maven to download Tycho and use that to define the build -* The modules section lists the locations of the POM files for the various projects that make up the application (remember that this is the parent POM) - -### A child POM ### -A typical child POM is shown below - -```xml - - 4.0.0 - uk.ac.stfc.isis.ibex.banner - eclipse-plugin - - CSS_ISIS - uk.ac.stfc.isis.ibex.client.tycho.parent - 1.0.0-SNAPSHOT - ../uk.ac.stfc.isis.ibex.client.tycho.parent - - 1.0.0-SNAPSHOT - -``` - -Basically it is very simple - it points at the parent POM to get most of its information. - -The packaging type is defined a eclipse-plugin. This is a packaging type defined by Tycho, Maven itself has no idea what this means. 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. - -### Creating an application ### - -In IBEX we define a separate project called `uk.ac.stfc.isis.ibex.client.product` which defines how the product is built. It has a POM file of packaging type eclipse-repository. - -```xml - - 4.0.0 - 1.0.0-SNAPSHOT - uk.ac.stfc.isis.ibex - eclipse-repository - - CSS_ISIS - uk.ac.stfc.isis.ibex.client.tycho.parent - 1.0.0-SNAPSHOT - ../uk.ac.stfc.isis.ibex.client.tycho.parent - - - - - - org.eclipse.tycho - tycho-p2-director-plugin - ${tycho.version} - - - - materialize-products - - materialize-products - - - - - archive-products - - archive-products - - - - - - - -``` - -The key area is the materialize-products section, this tells Tycho to actually create the product. Without this the build runs and checks everything is okay, but does not produce an executable. diff --git a/doc/client/getting_started/checked_pr.png b/doc/client/getting_started/checked_pr.png deleted file mode 100644 index 820c03980..000000000 Binary files a/doc/client/getting_started/checked_pr.png and /dev/null differ diff --git a/doc/client/getting_started/clone.png b/doc/client/getting_started/clone.png deleted file mode 100644 index a2ece1b0f..000000000 Binary files a/doc/client/getting_started/clone.png and /dev/null differ diff --git a/doc/client/getting_started/create_branch.png b/doc/client/getting_started/create_branch.png deleted file mode 100644 index 6ce56926b..000000000 Binary files a/doc/client/getting_started/create_branch.png and /dev/null differ diff --git a/doc/client/getting_started/new_branch.png b/doc/client/getting_started/new_branch.png deleted file mode 100644 index 45e17664c..000000000 Binary files a/doc/client/getting_started/new_branch.png and /dev/null differ diff --git a/doc/client/getting_started/open_a_pull_request.png b/doc/client/getting_started/open_a_pull_request.png deleted file mode 100644 index ba75a612b..000000000 Binary files a/doc/client/getting_started/open_a_pull_request.png and /dev/null differ diff --git a/doc/client/getting_started/pull_request_start.png b/doc/client/getting_started/pull_request_start.png deleted file mode 100644 index 7daf31315..000000000 Binary files a/doc/client/getting_started/pull_request_start.png and /dev/null differ diff --git a/doc/client/getting_started/pushed_branch.png b/doc/client/getting_started/pushed_branch.png deleted file mode 100644 index 910341ec5..000000000 Binary files a/doc/client/getting_started/pushed_branch.png and /dev/null differ diff --git a/doc/client/getting_started/start.png b/doc/client/getting_started/start.png deleted file mode 100644 index 858317998..000000000 Binary files a/doc/client/getting_started/start.png and /dev/null differ diff --git a/doc/conf.py b/doc/conf.py index d2c168070..19b32a84f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -38,6 +38,8 @@ "sphinx.ext.intersphinx", # Add links to source code in API docs "sphinx.ext.viewcode", + # Redirects + "sphinx_reredirects", ] napoleon_google_docstring = True napoleon_numpy_docstring = False @@ -81,3 +83,10 @@ spelling_warning = True spelling_show_suggestions = True spelling_suggestion_limit = 3 + +redirects = { + "client/GUI-Getting-Started": "GUI-Building.html", + "client/eclipse/Creating-the-IBEX-Developer-Version-of-Eclipse": "../compiling/Building-the-GUI.html#gui-build-install-eclipse", # noqa E501 + "client/eclipse/Dictionary-setup": "Common-Eclipse-Issues.html#adding-a-dictionary-to-eclipse-s-spelling-checker", # noqa E501 + "client/getting_started/GUI-Development-Workflow": "../../processes/git_and_github/Git-workflow.html", # noqa E501 +} diff --git a/doc/iocs/compiling/Developer-Server-Build.md b/doc/iocs/compiling/Developer-Server-Build.md index 935904b94..bac05a4dc 100644 --- a/doc/iocs/compiling/Developer-Server-Build.md +++ b/doc/iocs/compiling/Developer-Server-Build.md @@ -5,15 +5,17 @@ It is possible to use one of the intermediate outputs from a build server as the ## EPICS You need to be using a Visual Studio compatible with the build server, currently `Visual Studio 2022` -> [!TIP] ->### Quick Instructions -> Run `install_developer_build.bat` in either `\\isis.cclrc.ac.uk\inst$\Kits$\CompGroup\ICP\developer\EPICS` (for 64bit builds, what you usually need) or `\\isis.cclrc.ac.uk\inst$\Kits$\CompGroup\ICP\developer\EPICS32` (for 32 bit builds, only if you have to build/test a specific driver needing 32bit versions). It will prompt you to choose from normal/debug/static - in most cases `normal` +:::{tip} +**Quick Instructions** + +Run `install_developer_build.bat` in either `\\isis.cclrc.ac.uk\inst$\Kits$\CompGroup\ICP\developer\EPICS` (for 64bit builds, what you usually need) or `\\isis.cclrc.ac.uk\inst$\Kits$\CompGroup\ICP\developer\EPICS32` (for 32 bit builds, only if you have to build/test a specific driver needing 32bit versions). It will prompt you to choose from normal/debug/static - in most cases `normal` is what you want and is what is deployed to an instrument, `static` and `debug` are for special cases/testing +::: +:::{note} +If you just want a recent EPICS build to run somewhere and do not need to be able to develop using it, you just need to run the `install_to_inst.bat` in the appropriate build on `kits$` when connected from the machine you want to install it on +::: -> [!NOTE] -> if you just want a recent EPICS build to run somewhere and do not need to be able to develop using it, you just need to run the `install_to_inst.bat` in the appropriate build on `kits$` when connected from the machine you want to install it on -
Details (not normally needed) If you wish to use a `debug` build, replace `x64` in paths below with `x64-debug` diff --git a/doc/overview/First-Time-Build.md b/doc/overview/First-Time-Build.md index ae6672340..4374066eb 100644 --- a/doc/overview/First-Time-Build.md +++ b/doc/overview/First-Time-Build.md @@ -16,6 +16,7 @@ Download and install [Strawberry Perl](http://strawberryperl.com/) See [Install Visual Studio](/iocs/compiling/Install-Visual-Studio) +{#first_time_install_java} ## Install Java JDK Install **OpenJDK 21 hotspot** from https://adoptium.net/?variant=openjdk21&jvmVariant=hotspot (the MSI installer is fine, tick all the boxes when it asks you which components to install) @@ -26,6 +27,7 @@ Install **OpenJDK 21 hotspot** from https://adoptium.net/?variant=openjdk21&jvmV You may wish to install some optional java components [as detailed here](#developer_upgrade_java). +{#first_time_install_maven} ## Install Maven Create `C:\Tools\` @@ -37,6 +39,7 @@ _System Properties - Environment Variables - Path - New -`C:\Tools\apache-maven- The Windows Tips from the above link says you should add maven to the PATH in the user variables. If it does not recognise mvn -v afterwards, then try to add it to the list of variables in PATH in System variables. +{#first_time_install_git} ## Install Git Install Git [Getting-started-with-Git-and-GitHub](/processes/git_and_github/Getting-started-with-Git-and-GitHub) @@ -53,6 +56,7 @@ Install `\\isis.cclrc.ac.uk\inst$\kits$\CompGroup\Utilities\MOXA Nport Software\ To easily add `EPICSTerm.bat` to the start menu after copying EPICS, run `C:\Instrument\Apps\EPICS\add_epicsterm_to_start_menu.bat` +{#first_time_install_uktena} ## Install the uktena python distribution See [Building and installing the uktena python distribution](/system_components/python/Building-and-installing-uktena) @@ -86,7 +90,7 @@ Due to a change in admin provisioning on computers, you may need to use the admi ## Building the GUI -Please see [Building the GUI](/client/getting_started/Building-the-GUI). +Please see [Building the GUI](/client/compiling/Building-the-GUI). ## Setting up the configurations & scripting directory diff --git a/doc/processes/dev_processes/Dependency-Updates.md b/doc/processes/dev_processes/Dependency-Updates.md index 46c117795..757f784d1 100644 --- a/doc/processes/dev_processes/Dependency-Updates.md +++ b/doc/processes/dev_processes/Dependency-Updates.md @@ -29,7 +29,7 @@ General update process: - Some repositories are updated "in-place". Do upgrade these, simply delete and then re-add them to the target platform, when they are re-added they will pick up the latest versions. - For maven dependencies referenced in target platform, look up latest version on maven central then update the version number in target platform to correspond. If the version numbers are hardcoded in `feature.xml` or `MANIFEST.MF` for individual plugins, update it there too. -**Note: when updating the eclipse framework itself, you will need to download the same eclipse IDE with the same version number or else some jars may not be found. You also need to update `client.tycho.parent` - see below for details. Make sure you update the [gui build wiki page](/client/getting_started/Building-the-GUI) to ensure new starters get the correct version.** +**Note: when updating the eclipse framework itself, you will need to download the same eclipse IDE with the same version number or else some jars may not be found. You also need to update `client.tycho.parent` - see below for details. Make sure you update the [gui build wiki page](/client/compiling/Building-the-GUI) to ensure new starters get the correct version.** ### Parent POM diff --git a/doc/system_components/python/Building-and-installing-uktena.md b/doc/system_components/python/Building-and-installing-uktena.md index 084e34be1..0e41df6a0 100644 --- a/doc/system_components/python/Building-and-installing-uktena.md +++ b/doc/system_components/python/Building-and-installing-uktena.md @@ -44,8 +44,9 @@ The first time you set up python, assuming you've never installed it previously, The uktena python distributions uses released versions of all dependencies by default. However, you can install development versions of libraries into it easily using `pip` editable installs. -> [!NOTE] -> If you have not come across optional dependencies like `[dev]` before, read about them [here](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-and-requirements). +:::{seealso} +If you have not come across optional dependencies like `[dev]` before, read about them [here](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-and-requirements). +::: ### Dev process - Check out the library you want to develop into `c:\instrument\dev\some_library` @@ -69,9 +70,9 @@ You can now make changes in `c:\instrument\dev\some_library`. Once you are happy with your changes locally, commit and push them from `c:\instrument\dev\some_library` as usual. - In order to pick up the changes in future built versions of uktena, the changes will need to be released to pypi. -> [!NOTE] -> -> Our python dependencies, along with many other external dependencies, all define a `[dev]` optional dependency group which contains dev-only dependencies (like linters, documentation build tools, debugging tools and so on). If you are editable-installing an external library, it may use a different convention - consult that library's documentation or `pyproject.toml` to see which dependency groups are available. +:::{tip} +Our python dependencies, along with many other external dependencies, all define a `[dev]` optional dependency group which contains dev-only dependencies (like linters, documentation build tools, debugging tools and so on). If you are editable-installing an external library, it may use a different convention - consult that library's documentation or `pyproject.toml` to see which dependency groups are available. +::: To go back to the released version of the dependencies, you can run `c:\instrument\apps\python3\python.exe -m pip uninstall some_library` to remove your development version, followed by `c:\instrument\apps\python3\python.exe -m pip install some_library` to reinstall the released version from pypi. diff --git a/doc/system_components/python/Python-conventions.md b/doc/system_components/python/Python-conventions.md index 43d24a554..0e1673825 100644 --- a/doc/system_components/python/Python-conventions.md +++ b/doc/system_components/python/Python-conventions.md @@ -7,10 +7,11 @@ We try to follow [PEP8](https://www.python.org/dev/peps/pep-0008/) for coding st A clear exception is when it comes to line length; PEP8 suggests a line length limit of 79 characters but defaults to 100, but PyCharm defaults to 120. I recommend following PEP8 and modifying PyCharm default to 100 on this (See: `File -> Settings -> Editor -> Code Style -> Python -> Wrapping and Braces -> Hard wrap at: `). -> [!IMPORTANT] -> We have a [Ruff config](https://github.com/ISISComputingGroup/reusable-workflows/blob/main/ruff.toml), you can setup ruff to work with most IDE's and then use our [config](https://github.com/ISISComputingGroup/reusable-workflows/blob/main/ruff.toml) to lint your code, or run ruff from command line (`%PYTHON3% -m ruff check --config="C:\Instrument\Dev\reusable-workflows\ruff.toml"`) before making a pull request, standards compliance will be enforced by this config at pull request. So before making a pull request you should ensure any files you have changed have been formatted by ruff, and pass its checks. Ruff can also automatically fix many violations. -> -> Ruff should be run from the base directory of any project you are working in, for example in `DeviceEmulator`, it should be run from `master`, not from, for example `DeviceEmulator\master\lewis_emulators\eurotherm` +:::{important} +We have a [Ruff config](https://github.com/ISISComputingGroup/reusable-workflows/blob/main/ruff.toml), you can setup ruff to work with most IDE's and then use our [config](https://github.com/ISISComputingGroup/reusable-workflows/blob/main/ruff.toml) to lint your code, or run ruff from command line (`%PYTHON3% -m ruff check --config="C:\Instrument\Dev\reusable-workflows\ruff.toml"`) before making a pull request, standards compliance will be enforced by this config at pull request. So before making a pull request you should ensure any files you have changed have been formatted by ruff, and pass its checks. Ruff can also automatically fix many violations. + +Ruff should be run from the base directory of any project you are working in, for example in `DeviceEmulator`, it should be run from `master`, not from, for example `DeviceEmulator\master\lewis_emulators\eurotherm` +::: For new repos containing python you should add the following [workflow](https://github.com/ISISComputingGroup/reusable-workflows/blob/main/.github/workflows/linters.yml) to ensure standards compliance. diff --git a/pyproject.toml b/pyproject.toml index 571d322dd..2af204be2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,6 +30,7 @@ dependencies = [ "sphinx-autobuild", "linkify-it-py", "sphinxcontrib-spelling", + "sphinx-reredirects", "pytest", ]