Skip to content

Commit c171699

Browse files
committed
update README to include tips on running code outside of Gradle/IDE
1 parent 355510d commit c171699

1 file changed

Lines changed: 58 additions & 3 deletions

File tree

README.MD

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -224,14 +224,14 @@ public static void main(String[] args) throws Exception {
224224
}
225225
```
226226

227-
# Running an Example
227+
# Running an Example Using Gradles
228228

229229
A Gradle task is defined for running each example. To run an example:
230230
1. Expand the **Gradle** tab (likely along the right side of the IDE).
231231
1. Expand **Nuix-Java-Engine-Baseline** -> **Tasks** -> **examples**.
232232
1. Double-click one of the tasks to run the corresponding example (**BasicInitialization** is a good initial test).
233233

234-
# Gradle Build File
234+
## Gradle Build File
235235

236236
The `plugins` section allows us to include plugins that provide functionality to our build file. We include the `java` plugin which provides various functionality for a Java project.
237237

@@ -317,9 +317,64 @@ def defaultJvmArgs = [
317317

318318
Beyond that, a series of [JavaExec tasks](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.JavaExec.html) are defined, each which provides a way to run one of the examples.
319319

320-
# License
320+
# Running an Example Outside Gradle
321+
322+
Gradle simplifies running the examples, but what is needed to run an example (or your own code) outside of Gradle? We need to take similar steps to what Gradle would be doing:
323+
- Start a JVM (Java Virtual Machine) to run the program.
324+
- Make sure that the engine release sub-directories `bin` and `bin\x86` can be resolved via the `PATH` environment variable.
325+
- Make sure your JAR can be resolved on the JVM classpath.
326+
- Make sure the Nuix dependency JAR files in the engine release `lib` sub-directory can be resolved on the JVM classpath.
327+
- Make sure we know the entry point to our program. The entry point is the Java class containing the `public static void main(String[] args)` method to run.
328+
329+
## Make Sure Java is Installed
330+
It is assumed that you have Java installed and that running the command `java` on the console will succeed.
331+
332+
## `PATH` References to `bin` and `bin/x86`
333+
You will need to make sure that the `PATH` environment variable for the JVM process points to the engine release sub-directories `bin` and `bin\x86`. This can be accomplished different ways. The easiest is to add those paths to the `PATH` environment variable. There are ways to set these temporarily for the JVM process you start. For example you could use a batch file and `SET LOCAL` / `END LOCAL` ([doc](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/setlocal)) in combination with `SET` ([doc](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1)) or start your program via something like the .NET class [Process](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.process?view=net-7.0) which allows for customizing the environment variables just for a process it starts via
334+
335+
```csharp
336+
Process nuixProcess = new Process();
337+
...
338+
...
339+
string engineDir = "C:\\EngineRelease";
340+
string engineBinDir = engineDir + "\\bin";
341+
string enginex86BinDir = engineBinDir + "\\x86";
342+
string existingPath = Environment.GetEnvironment("PATH");
343+
nuixProcess.StartInfo.EnvironmentVariables.Add("PATH", existingPath+";"+engineBinDir+";"+enginex86BinDir );
344+
```
345+
346+
## Construct the Command
321347

348+
The command takes the basic form:
349+
350+
```
351+
java -cp "<Engine Lib Directory>/*;<Path to Jar>" <Main Class>
352+
```
353+
354+
If my engine release `lib` directory is located at `C:\EngineRelease\lib`, my compiled JAR is located at `C:\MyApp\MyCustomNuixApp-v1.0.0.jar` and my `public static void main(String[] args)` method exists in a class `com.company.CustomNuixApp` then the command would look like this:
355+
356+
```
357+
java -cp "C:/EngineRelease/lib/*;C:/MyApp/MyCustomNuixApp-v1.0.0.jar" com.company.CustomNuixApp
322358
```
359+
360+
Some things to note:
361+
362+
- The class path references use forward slashes (`/`) rather than the Windows norm of using back slashes (`\`).
363+
- The engine lib directory class path reference ends with `/*` to include all JAR files in that directory.
364+
- The program JAR reference is an absolute reference to the JAR file (it could be reference to its containing directory though).
365+
- The class path entries are delimited with a semicolon (`;`).
366+
- The *last argument* is the fully qualified name (package and class name) of the class containing the entry point we are running.
367+
368+
# Where to Get Help
369+
370+
Having trouble getting things up and running? Here are several places you can seek assistance:
371+
372+
- Create a [new Issue](https://github.com/Nuix/Nuix-Java-Engine-Baseline/issues/new)
373+
- Ask on the [Nuix Community Forums](https://forums.nuix.com/)
374+
- Contact [Nuix Support](https://nuix.service-now.com/support)
375+
376+
# License
377+
323378
Copyright 2023 Nuix
324379

325380
Licensed under the Apache License, Version 2.0 (the "License");

0 commit comments

Comments
 (0)