Skip to content

Commit 65f6595

Browse files
zspitzerzspitzer
committed
add jfr support, cleanup readme, add examples
1 parent 369f900 commit 65f6595

File tree

3 files changed

+440
-53
lines changed

3 files changed

+440
-53
lines changed

‎EXAMPLES.md‎

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
# Script Runner Examples
2+
3+
Practical examples and use cases for the Lucee Script Runner.
4+
5+
## Table of Contents
6+
7+
- [Quick Start Examples](#quick-start-examples)
8+
- [Shell-Specific Usage](#shell-specific-usage)
9+
- [Java Flight Recorder (JFR) Profiling](#java-flight-recorder-jfr-profiling)
10+
- [Concurrent Execution](#concurrent-execution)
11+
- [Working Directory Examples](#working-directory-examples)
12+
- [Testing Extensions](#testing-extensions)
13+
- [CI/CD Integration](#cicd-integration)
14+
15+
## Quick Start Examples
16+
17+
### Running from Different Locations
18+
19+
```bash
20+
# From the script-runner directory (simple)
21+
ant -Dwebroot="/path/to/your/project" -Dexecute="yourscript.cfm"
22+
23+
# From your project directory (recommended for external projects)
24+
ant -buildfile="/path/to/script-runner/build.xml" -Dwebroot="." -Dexecute="yourscript.cfm"
25+
26+
# From any directory with absolute paths
27+
ant -buildfile="C:\tools\script-runner\build.xml" -Dwebroot="C:\work\myproject" -Dexecute="test.cfm"
28+
29+
# Execute a script below the webroot
30+
ant -buildfile="C:\tools\script-runner\build.xml" -Dwebroot="C:\work\myproject" -Dexecute="extended/index.cfm"
31+
```
32+
33+
### Testing Lucee Extensions
34+
35+
```bash
36+
# Testing Lucee Spreadsheet from its directory
37+
cd D:\work\lucee-spreadsheet
38+
ant -buildfile=D:\work\script-runner\build.xml -Dwebroot=. -Dexecute=/test/index.cfm
39+
40+
# Testing with specific Lucee version
41+
ant -buildfile=D:\work\script-runner\build.xml -DluceeVersionQuery=6.2/stable/jar -Dwebroot=D:\work\lucee-spreadsheet -Dexecute=/test/index.cfm
42+
43+
# Testing with a locally built Lucee JAR (for Lucee developers)
44+
ant -buildfile=D:\work\script-runner\build.xml -DluceeJar="D:\work\lucee\loader\target\lucee.jar" -Dwebroot=D:\work\lucee-spreadsheet -Dexecute=/test/index.cfm
45+
46+
# With unique working directory for concurrent runs
47+
ant -buildfile=D:\work\script-runner\build.xml -DuniqueWorkingDir=true -Dwebroot=D:\work\lucee-spreadsheet -Dexecute=/test/index.cfm
48+
```
49+
50+
## Shell-Specific Usage
51+
52+
### PowerShell
53+
54+
Use double quotes for paths with spaces. Single quotes also work (especially in scripts to avoid variable expansion).
55+
56+
```powershell
57+
# No spaces in paths
58+
ant -buildfile "C:\tools\script-runner\build.xml" -Dwebroot="C:\work\myproject" -Dexecute="test.cfm"
59+
60+
# Paths with spaces
61+
ant -buildfile "C:\tools\script-runner\build.xml" -Dwebroot="C:\work\my project" -Dexecute="test.cfm" -DuniqueWorkingDir=true
62+
63+
# Using single quotes to avoid variable expansion in scripts
64+
ant -buildfile='C:\tools\script-runner\build.xml' -Dwebroot='C:\work\project' -Dexecute='test.cfm'
65+
```
66+
67+
### Command Prompt (Windows)
68+
69+
Quotes are only needed if the path contains spaces. You can quote just the value or the entire parameter.
70+
71+
```cmd
72+
REM No spaces in paths (no quotes needed)
73+
ant -buildfile=C:\tools\script-runner\build.xml -Dwebroot=C:\work\myproject -Dexecute=test.cfm -DuniqueWorkingDir=true
74+
75+
REM Spaces in paths (quotes required)
76+
ant -buildfile="C:\tools\script-runner\build.xml" -Dwebroot="C:\work\my project" -Dexecute="test.cfm" -DuniqueWorkingDir=true
77+
78+
REM Or quote the entire parameter (especially useful in batch files)
79+
ant "-buildfile=C:\Program Files\script-runner\build.xml" "-Dwebroot=C:\My Projects\test" -Dexecute=test.cfm
80+
```
81+
82+
### Bash/WSL (Linux)
83+
84+
Use forward slashes and Linux-style paths. Quotes only if the path has spaces.
85+
86+
```bash
87+
# No spaces in paths (no quotes needed)
88+
ant -buildfile /mnt/d/work/script-runner/build.xml -Dwebroot=/mnt/d/work/myproject -Dexecute=test.cfm -DuniqueWorkingDir=true
89+
90+
# Spaces in paths (quotes required)
91+
ant -buildfile "/mnt/d/work/script-runner/build.xml" -Dwebroot="/mnt/d/work/my project" -Dexecute="test.cfm" -DuniqueWorkingDir=true
92+
```
93+
94+
### Quick Reference Table
95+
96+
| Shell | Example Command |
97+
|--------------- |------------------------------------------------------------------------------------------------------------------|
98+
| PowerShell | `ant -buildfile "C:\tools\script-runner\build.xml" -Dwebroot="C:\work\my project" -Dexecute="test.cfm" -DuniqueWorkingDir=true` |
99+
| Command Prompt | `ant -buildfile=C:\tools\script-runner\build.xml -Dwebroot=C:\work\myproject -Dexecute=test.cfm -DuniqueWorkingDir=true` |
100+
| Bash/WSL | `ant -buildfile /mnt/d/work/script-runner/build.xml -Dwebroot=/mnt/d/work/myproject -Dexecute=test.cfm -DuniqueWorkingDir=true` |
101+
102+
**Key Points:**
103+
104+
- **PowerShell:** Use double quotes for paths with spaces. Single quotes work too (good for avoiding variable expansion)
105+
- **Command Prompt:** Quotes only if path has spaces. Can quote just the value or the whole parameter
106+
- **Bash/WSL:** Use forward slashes. Quotes only if path has spaces. Don't use Windows backslashes or drive letters
107+
- **Windows:** Never use trailing backslashes. Ever.
108+
- **All shells:** Don't escape quotes unless you like pain
109+
- **Debugging:** If Ant can't find your file, your path or quotes are wrong. Period.
110+
111+
## Java Flight Recorder (JFR) Profiling
112+
113+
Enable JFR to capture detailed performance data during script execution.
114+
115+
### Basic JFR Usage
116+
117+
```bash
118+
ant -DFlightRecording=true -Dwebroot="." -Dexecute="yourscript.cfm"
119+
```
120+
121+
### What JFR Captures
122+
123+
- Creates JFR recording files in `logs/{timestamp}-j{java.version}.jfr`
124+
- Captures CPU usage, memory allocation, garbage collection, thread activity
125+
- Settings: disk=true, dumponexit=true, maxsize=1024m, maxage=1d, settings=profile, path-to-gc-roots=true, stackdepth=128
126+
127+
### Custom JFR Output Path
128+
129+
```bash
130+
ant -DFlightRecording=true -DFlightRecordingFilename="D:/my-logs/custom.jfr" -Dwebroot="." -Dexecute="yourscript.cfm"
131+
```
132+
133+
### JFR API Access for Lucee
134+
135+
If you need Lucee to access JFR APIs directly (not just record), add the JFR module exports:
136+
137+
```bash
138+
ant -DjfrExports=true -Dwebroot="." -Dexecute="yourscript.cfm"
139+
```
140+
141+
This adds `--add-exports=jdk.jfr/jdk.jfr=ALL-UNNAMED` and `--add-opens=jdk.jfr/jdk.jfr=ALL-UNNAMED` to allow Lucee code to use the JFR API.
142+
143+
### Analyzing JFR Files
144+
145+
```bash
146+
# Print summary
147+
jfr print logs/250101-120530-j21.jfr
148+
149+
# Print specific events
150+
jfr print --events CPULoad,GarbageCollection logs/250101-120530-j21.jfr
151+
152+
# Convert to JSON
153+
jfr print --json logs/250101-120530-j21.jfr > output.json
154+
```
155+
156+
The `jfr` command-line tool is included in the JDK bin directory. For visual analysis, use JDK Mission Control (JMC) or import into profiling tools.
157+
158+
## Concurrent Execution
159+
160+
Multiple script-runner instances can be run simultaneously using unique working directories.
161+
162+
### Running Tests in Parallel
163+
164+
```bash
165+
# Run multiple instances concurrently
166+
ant -DuniqueWorkingDir="true" -Dexecute="test1.cfm" &
167+
ant -DuniqueWorkingDir="true" -Dexecute="test2.cfm" &
168+
ant -DuniqueWorkingDir="true" -Dexecute="test3.cfm" &
169+
wait
170+
```
171+
172+
Each instance will use a unique working directory named `temp-unique/{VERSION}-{TIMESTAMP}-{RANDOM}` (timestamp format: `yyMMdd-HHmmss`) to prevent conflicts.
173+
174+
## Working Directory Examples
175+
176+
### Default Mode (Single Instance)
177+
178+
```bash
179+
# Uses temp/lucee - fast, but single instance only
180+
ant -DuniqueWorkingDir=false -Dwebroot=. -Dexecute=test.cfm
181+
```
182+
183+
### Auto-Unique Mode (Concurrent Execution)
184+
185+
```bash
186+
# Uses temp-unique/{VERSION}-{TIMESTAMP}-{RANDOM}
187+
ant -DuniqueWorkingDir=true -Dwebroot=. -Dexecute=test.cfm
188+
```
189+
190+
### Custom Path Mode
191+
192+
```bash
193+
# Uses your specified directory
194+
ant -DuniqueWorkingDir=C:/fast/work -Dwebroot=. -Dexecute=test.cfm
195+
```
196+
197+
### Preserving Working Directory for Inspection
198+
199+
```bash
200+
# Don't cleanup before or after - useful for debugging
201+
ant -DpreCleanup=false -DpostCleanup=false -Dwebroot=. -Dexecute=test.cfm
202+
```
203+
204+
## Testing Extensions
205+
206+
### Testing a Built Extension
207+
208+
```bash
209+
# Install extension from dist/ directory and run tests
210+
ant -buildfile=script-runner/build.xml \
211+
-DluceeVersion="6.2.2.91" \
212+
-Dwebroot="$BITBUCKET_CLONE_DIR/lucee/test" \
213+
-DextensionDir="$BITBUCKET_CLONE_DIR/dist" \
214+
-Dexecute="bootstrap-tests.cfm" \
215+
-DtestAdditional="$BITBUCKET_CLONE_DIR/tests"
216+
```
217+
218+
### Testing with Debug Mode
219+
220+
```bash
221+
# Enable Java debugger on port 5000
222+
ant -Ddebugger=true -Dwebroot=. -Dexecute=test.cfm
223+
```
224+
225+
Then connect your IDE debugger to `localhost:5000`.
226+
227+
## CI/CD Integration
228+
229+
### GitHub Actions
230+
231+
```yaml
232+
- name: Checkout Lucee
233+
uses: actions/checkout@v2
234+
with:
235+
repository: lucee/lucee
236+
path: lucee
237+
238+
- name: Cache Maven packages
239+
uses: actions/cache@v3
240+
with:
241+
path: ~/.m2
242+
key: lucee-script-runner-maven-cache
243+
244+
- name: Cache Lucee files
245+
uses: actions/cache@v3
246+
with:
247+
path: _actions/lucee/script-runner/main/lucee-download-cache
248+
key: lucee-downloads
249+
250+
- name: Run Lucee Test Suite
251+
uses: lucee/script-runner@main
252+
with:
253+
webroot: ${{ github.workspace }}/lucee/test
254+
execute: bootstrap-tests.cfm
255+
luceeVersion: ${{ env.luceeVersion }}
256+
luceeVersionQuery: 5.4/stable/light # (optional, overrides luceeVersion)
257+
luceeJar: /path/to/local/lucee.jar # (optional, overrides both luceeVersion and luceeVersionQuery)
258+
extensions: # (optional list of extension guids to install)
259+
extensionDir: ${{ github.workspace }}/dist # (for testing building an extension with CI)
260+
antFlags: -d or -v etc # (optional, good for debugging any ant issues)
261+
compile: true # (optional, compiles all the cfml under the webroot)
262+
luceeCFConfig: /path/to/.CFConfig.json # pass in additional configuration
263+
debugger: true # (optional) runs with java debugging enabled on port 5000
264+
preCleanup: true # (purges Lucee working directory before starting)
265+
postCleanup: true # (purges Lucee working directory after finishing)
266+
uniqueWorkingDir: true # (optional) uses unique working directory for concurrent execution
267+
env:
268+
testLabels: pdf
269+
testAdditional: ${{ github.workspace }}/tests
270+
```
271+
272+
[GitHub Action Workflow Example](https://github.com/lucee/extension-pdf/blob/master/.github/workflows/main.yml)
273+
274+
This will:
275+
276+
- Checkout a copy of the Lucee codebase
277+
- Install any extension(s) (`*.lex`) found in `${{ github.workspace }}/dist`
278+
- Run all tests with the label of "pdf"
279+
- Run any additional tests found in the `/tests` directory of the current repository
280+
281+
### BitBucket Pipeline
282+
283+
```yaml
284+
image: atlassian/default-image:3
285+
286+
pipelines:
287+
default:
288+
- step:
289+
name: Build and Test
290+
caches:
291+
- maven
292+
script:
293+
- ant -noinput -verbose -buildfile build.xml
294+
artifacts:
295+
- dist/**
296+
- step:
297+
name: Checkout Lucee Script-runner, Lucee and run tests
298+
script:
299+
- git clone https://github.com/lucee/script-runner
300+
- git clone https://github.com/lucee/lucee
301+
- export testLabels="PDF"
302+
- echo $testLabels
303+
- ant -buildfile script-runner/build.xml -DluceeVersion="light-6.2.2.91" -Dwebroot="$BITBUCKET_CLONE_DIR/lucee/test" -DextensionDir="$BITBUCKET_CLONE_DIR/dist" -Dexecute="bootstrap-tests.cfm" -DtestAdditional="$BITBUCKET_CLONE_DIR/tests"
304+
```

0 commit comments

Comments
 (0)