Skip to content

Commit 7e5b0ab

Browse files
elucashelucash
committed
manual processor argument test scripts
1 parent 165d4eb commit 7e5b0ab

7 files changed

Lines changed: 562 additions & 0 deletions

File tree

‎processor-arguments-test/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.generated/
2+
lib/

‎processor-arguments-test/README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
2+
# Immutables Annotation Processor Options Test
3+
4+
This directory contains manual tests for Immutables annotation processor options, specifically:
5+
6+
1. `-Aimmutables.annotations.pick` - Controls which annotation packages are used in generated code
7+
2. `-Aimmutables.guava.suppress` - Forces JDK-only collections even when Guava is on classpath
8+
9+
## Directory Structure
10+
11+
```
12+
immutables-annotation-processor-test/
13+
├── lib/ # Downloaded JAR dependencies
14+
│ ├── value-2.12.0-rc0.jar # Immutables annotation processor
15+
│ ├── value-annotations-2.12.0-rc0.jar # Immutables annotations
16+
│ ├── guava-33.0.0-jre.jar # Google Guava
17+
│ ├── jakarta.annotation-api-3.0.0.jar # Jakarta annotations
18+
│ └── javax.annotation-api-1.3.2.jar # Javax annotations
19+
├── src/com/example/ # Sample Java source files
20+
│ ├── Person.java # Simple immutable for annotations test
21+
│ └── Team.java # Immutable with collections for Guava test
22+
├── generated/ # Generated code output (created when tests run)
23+
├── download-jars.sh # Script to download all JAR dependencies
24+
├── test-annotations-pick.sh # Test script for -Aimmutables.annotations.pick
25+
├── test-guava-suppress.sh # Test script for -Aimmutables.guava.suppress
26+
└── README.md # This file
27+
```
28+
29+
## Getting Started
30+
31+
### Download Dependencies
32+
33+
If the `lib/` directory is empty (e.g., after cloning the repository), run the download script to fetch all required JARs from Maven Central:
34+
35+
```bash
36+
chmod +x download-jars.sh
37+
./download-jars.sh
38+
```
39+
40+
This will download:
41+
- Immutables 2.12.0-rc0 (annotation processor and annotations)
42+
- Guava 33.0.0-jre
43+
- Jakarta Annotation API 3.0.0
44+
- Javax Annotation API 1.3.2
45+
46+
The script is idempotent - it will skip files that already exist, so it's safe to run multiple times.
47+
48+
## Dependencies
49+
50+
- **Immutables 2.12.0-rc0**: The version being tested
51+
- **Guava 33.0.0-jre**: Latest stable Guava for testing suppression
52+
- **Jakarta Annotation API 3.0.0**: For testing jakarta annotation generation
53+
- **Javax Annotation API 1.3.2**: For testing javax annotation generation
54+
55+
## Test 1: Annotations Pick (`-Aimmutables.annotations.pick`)
56+
57+
This option controls which annotation packages Immutables uses in generated code.
58+
59+
### Usage
60+
61+
```bash
62+
chmod +x test-annotations-pick.sh
63+
./test-annotations-pick.sh
64+
```
65+
66+
### What it tests
67+
68+
The script compiles `Person.java` with different values for `-Aimmutables.annotations.pick`:
69+
70+
1. **`jakarta`** - Uses `jakarta.annotation.Generated` and `jakarta.annotation.ParametersAreNonnullByDefault`
71+
2. **`javax`** - Uses `javax.annotation.Generated`
72+
3. **`javax+processing`** - Uses `javax.annotation.processing.Generated`
73+
4. **`legacy`** - Uses legacy `javax.annotation.*` packages
74+
5. **`none`** (empty value) - No processor-generated annotations
75+
76+
### Expected output
77+
78+
The script shows:
79+
- Which annotations are imported in the generated `ImmutablePerson.java`
80+
- Which annotations are applied to the class
81+
- Differences between jakarta vs javax vs none
82+
83+
### Generated code locations
84+
85+
After running, inspect the generated code:
86+
```
87+
generated/annotations-pick-jakarta/com/example/ImmutablePerson.java
88+
generated/annotations-pick-javax/com/example/ImmutablePerson.java
89+
generated/annotations-pick-javax-processing/com/example/ImmutablePerson.java
90+
generated/annotations-pick-legacy/com/example/ImmutablePerson.java
91+
generated/annotations-pick-none/com/example/ImmutablePerson.java
92+
```
93+
94+
## Test 2: Guava Suppress (`-Aimmutables.guava.suppress`)
95+
96+
This option forces the processor to ignore Guava even when it's on the classpath.
97+
98+
### Usage
99+
100+
```bash
101+
chmod +x test-guava-suppress.sh
102+
./test-guava-suppress.sh
103+
```
104+
105+
### What it tests
106+
107+
The script runs three compilation scenarios:
108+
109+
1. **Guava on classpath, NOT suppressed** - Should use `com.google.common.collect.ImmutableList/Set/Map`
110+
2. **Guava on classpath, BUT suppressed** - Should use JDK `Collections.unmodifiableList/Set/Map`
111+
3. **Guava NOT on classpath** - Baseline comparison, should match scenario 2
112+
113+
### Expected output
114+
115+
The script shows:
116+
- Whether Guava imports are present in generated code
117+
- What collection types are used in the generated fields
118+
- A diff command to compare the generated files
119+
120+
### Generated code locations
121+
122+
After running, inspect and compare:
123+
```
124+
generated/guava-not-suppressed/com/example/ImmutableTeam.java # Uses Guava
125+
generated/guava-suppressed/com/example/ImmutableTeam.java # Uses JDK only
126+
generated/guava-absent/com/example/ImmutableTeam.java # Uses JDK only
127+
```
128+
129+
Compare them:
130+
```bash
131+
diff generated/guava-not-suppressed/com/example/ImmutableTeam.java \
132+
generated/guava-suppressed/com/example/ImmutableTeam.java
133+
```
134+
135+
## Manual Testing
136+
137+
You can also run javac manually to test specific scenarios:
138+
139+
### Test annotations.pick manually
140+
141+
```bash
142+
javac -cp lib/value-annotations-2.12.0-rc0.jar:lib/jakarta.annotation-api-3.0.0.jar \
143+
-processorpath lib/value-2.12.0-rc0.jar \
144+
-proc:only \
145+
-s generated/manual-test \
146+
-Aimmutables.annotations.pick=jakarta \
147+
src/com/example/Person.java
148+
```
149+
150+
### Test guava.suppress manually
151+
152+
```bash
153+
javac -cp lib/value-annotations-2.12.0-rc0.jar:lib/guava-33.0.0-jre.jar \
154+
-processorpath lib/value-2.12.0-rc0.jar \
155+
-proc:only \
156+
-s generated/manual-test \
157+
-Aimmutables.guava.suppress \
158+
src/com/example/Team.java
159+
```
160+
161+
## Requirements
162+
163+
- Java 11 or later (for running javac)
164+
- bash shell
165+
- curl (for downloading dependencies)
166+
- Basic Unix tools (grep, diff)
167+
168+
## Documentation References
169+
170+
These options are documented in the Immutables documentation:
171+
172+
- **Annotation Processing Options**: `/newandnice.mdx` section "Annotation Processing Options"
173+
- **`-Aimmutables.annotations.pick`**: Controls javax vs jakarta vs none for standard annotations
174+
- **`-Aimmutables.guava.suppress`**: Forces JDK-only collections when Guava is present
175+
176+
## Cleaning Up
177+
178+
To clean all generated code:
179+
180+
```bash
181+
rm -rf generated/
182+
```
183+
184+
To start fresh (including downloads):
185+
186+
```bash
187+
rm -rf lib/ generated/
188+
```
189+
190+
Then re-download dependencies by running the test scripts again (or manually with curl).

‎processor-arguments-test/download-jars.sh‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
#!/bin/bash
2+
3+
# Download all required JAR dependencies for Immutables annotation processor testing
4+
# This script downloads JARs from Maven Central to the lib/ directory
5+
6+
set -e
7+
8+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
9+
LIB_DIR="$SCRIPT_DIR/lib"
10+
11+
# Maven Central base URL
12+
MAVEN_CENTRAL="https://repo1.maven.org/maven2"
13+
14+
# JAR definitions: groupId:artifactId:version:filename
15+
JARS=(
16+
"org.immutables:value:2.12.0-rc0:value-2.12.0-rc0.jar"
17+
"org.immutables:value-annotations:2.12.0-rc0:value-annotations-2.12.0-rc0.jar"
18+
"com.google.guava:guava:33.0.0-jre:guava-33.0.0-jre.jar"
19+
"jakarta.annotation:jakarta.annotation-api:3.0.0:jakarta.annotation-api-3.0.0.jar"
20+
"javax.annotation:javax.annotation-api:1.3.2:javax.annotation-api-1.3.2.jar"
21+
)
22+
23+
echo "=========================================="
24+
echo "Downloading JAR Dependencies"
25+
echo "=========================================="
26+
echo ""
27+
28+
# Create lib directory if it doesn't exist
29+
if [ ! -d "$LIB_DIR" ]; then
30+
echo "Creating lib directory: $LIB_DIR"
31+
mkdir -p "$LIB_DIR"
32+
echo ""
33+
fi
34+
35+
# Function to convert Maven coordinates to URL path
36+
# e.g., org.immutables:value:2.12.0-rc0 -> org/immutables/value/2.12.0-rc0
37+
maven_path() {
38+
local GROUP_ID=$1
39+
local ARTIFACT_ID=$2
40+
local VERSION=$3
41+
local FILENAME=$4
42+
43+
# Replace dots with slashes in groupId
44+
local GROUP_PATH="${GROUP_ID//.//}"
45+
46+
echo "${MAVEN_CENTRAL}/${GROUP_PATH}/${ARTIFACT_ID}/${VERSION}/${FILENAME}"
47+
}
48+
49+
# Download each JAR
50+
DOWNLOADED=0
51+
SKIPPED=0
52+
FAILED=0
53+
54+
for jar_def in "${JARS[@]}"; do
55+
# Parse the JAR definition
56+
IFS=':' read -r GROUP_ID ARTIFACT_ID VERSION FILENAME <<< "$jar_def"
57+
58+
TARGET_FILE="$LIB_DIR/$FILENAME"
59+
60+
# Check if already downloaded
61+
if [ -f "$TARGET_FILE" ]; then
62+
echo "✓ Already exists: $FILENAME"
63+
((SKIPPED++))
64+
continue
65+
fi
66+
67+
# Build Maven Central URL
68+
URL=$(maven_path "$GROUP_ID" "$ARTIFACT_ID" "$VERSION" "$FILENAME")
69+
70+
echo "Downloading: $FILENAME"
71+
echo " From: $URL"
72+
73+
# Download with curl
74+
if curl -f -L -o "$TARGET_FILE" "$URL" 2>/dev/null; then
75+
FILE_SIZE=$(ls -lh "$TARGET_FILE" | awk '{print $5}')
76+
echo " ✓ Downloaded successfully ($FILE_SIZE)"
77+
((DOWNLOADED++))
78+
else
79+
echo " ✗ Failed to download!"
80+
((FAILED++))
81+
# Remove partial download if it exists
82+
rm -f "$TARGET_FILE"
83+
fi
84+
85+
echo ""
86+
done
87+
88+
echo "=========================================="
89+
echo "Download Summary"
90+
echo "=========================================="
91+
echo ""
92+
echo "Downloaded: $DOWNLOADED"
93+
echo "Skipped (already exists): $SKIPPED"
94+
echo "Failed: $FAILED"
95+
echo ""
96+
97+
if [ $FAILED -gt 0 ]; then
98+
echo "⚠️ Some downloads failed. Please check your internet connection"
99+
echo " and try again."
100+
exit 1
101+
fi
102+
103+
echo "All dependencies are ready in: $LIB_DIR"
104+
echo ""
105+
echo "JAR files:"
106+
ls -lh "$LIB_DIR" | tail -n +2
107+
108+
echo ""
109+
echo "You can now run the test scripts:"
110+
echo " ./test-annotations-pick.sh"
111+
echo " ./test-guava-suppress.sh"

‎processor-arguments-test/src/com/example/Person.java‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
package com.example;
2+
3+
import org.immutables.value.Value;
4+
5+
/**
6+
* Simple immutable person to test annotation processor options.
7+
* This will test -Aimmutables.annotations.pick to see which @Generated annotation is used.
8+
*/
9+
@Value.Immutable
10+
public interface Person {
11+
String name();
12+
int age();
13+
String email();
14+
}

‎processor-arguments-test/src/com/example/Team.java‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
package com.example;
2+
3+
import org.immutables.value.Value;
4+
import java.util.List;
5+
import java.util.Set;
6+
import java.util.Map;
7+
8+
/**
9+
* Immutable team with collections to test -Aimmutables.guava.suppress.
10+
* When Guava is on classpath but suppressed, this should generate JDK collections
11+
* instead of Guava ImmutableList/ImmutableSet/ImmutableMap.
12+
*/
13+
@Value.Immutable
14+
public interface Team {
15+
String name();
16+
List<String> members();
17+
Set<String> tags();
18+
Map<String, String> metadata();
19+
}

0 commit comments

Comments
 (0)