0
# Installation and Configuration
1

2
APIs for discovering GraalVM installation paths, version information, and managing configuration options across languages and tools.
3

4
## Capabilities
5

6
### GraalVM Installation Discovery
7

8
Programmatic access to GraalVM installation paths and metadata for runtime configuration.
9

10
```java { .api }
11
/**
12
 * Abstract base class for finding GraalVM installation paths and metadata
13
 */
14
public abstract class HomeFinder {
15
    /** Get singleton instance for current environment */
16
    public static HomeFinder getInstance();
17
    
18
    /** Get GraalVM home directory path */
19
    public abstract String getHomeFolder();
20
    
21
    /** Get GraalVM version information */
22
    public abstract Version getVersion();
23
    
24
    /** Get map of language ID to installation path */
25
    public abstract Map<String, String> getLanguageHomes();
26
    
27
    /** Get map of tool ID to installation path */
28
    public abstract Map<String, String> getToolHomes();
29
    
30
    /** Check if running in GraalVM distribution */
31
    public boolean isGraalVMDistribution();
32
    
33
    /** Get relative path within GraalVM installation */
34
    public String getRelativePath(String path);
35
}
36
```
37

38
**Usage Examples:**
39

40
```java
41
import org.graalvm.home.*;
42

43
public class InstallationDiscovery {
44
    public void discoverGraalVM() {
45
        HomeFinder finder = HomeFinder.getInstance();
46
        
47
        // Get installation details
48
        String graalHome = finder.getHomeFolder();
49
        Version version = finder.getVersion();
50
        
51
        System.out.println("GraalVM Home: " + graalHome);
52
        System.out.println("Version: " + version.toString());
53
        
54
        // Check available languages
55
        Map<String, String> languages = finder.getLanguageHomes();
56
        for (Map.Entry<String, String> entry : languages.entrySet()) {
57
            System.out.println("Language " + entry.getKey() + 
58
                             " at: " + entry.getValue());
59
        }
60
        
61
        // Check available tools
62
        Map<String, String> tools = finder.getToolHomes();
63
        for (Map.Entry<String, String> entry : tools.entrySet()) {
64
            System.out.println("Tool " + entry.getKey() + 
65
                             " at: " + entry.getValue());
66
        }
67
        
68
        // Conditional behavior based on distribution
69
        if (finder.isGraalVMDistribution()) {
70
            // Use GraalVM-specific features
71
            String libPath = finder.getRelativePath("lib/graalvm");
72
        }
73
    }
74
}
75
```
76

77
### Version Information
78

79
Comprehensive version handling with parsing, comparison, and metadata access.
80

81
```java { .api }
82
/**
83
 * Version information with parsing and comparison support
84
 */
85
public final class Version implements Comparable<Version> {
86
    /** Get current GraalVM version */
87
    public static Version getCurrent();
88
    
89
    /** Create version from version numbers */
90
    public static Version create(int... versions);
91
    
92
    /** Parse version from string */
93
    public static Version parse(String versionString);
94
    
95
    /** Get major version number */
96
    public int getMajor();
97
    
98
    /** Get minor version number */
99
    public int getMinor();
100
    
101
    /** Get patch version number */
102
    public int getPatch();
103
    
104
    /** Get build number if available */
105
    public int getBuild();
106
    
107
    /** Get version qualifier (alpha, beta, rc, etc.) */
108
    public String getQualifier();
109
    
110
    /** Check if this is a snapshot version */
111
    public boolean isSnapshot();
112
    
113
    /** Check if this is a release version */
114
    public boolean isRelease();
115
    
116
    /** Check if this is a development version */
117
    public boolean isDevelopment();
118
    
119
    /** Compare with another version */
120
    public int compareTo(Version other);
121
    
122
    /** Check if version is at least given version */
123
    public boolean isAtLeast(Version minimum);
124
    
125
    /** Check if version is older than given version */
126
    public boolean isOlderThan(Version maximum);
127
    
128
    /** Get string representation */
129
    public String toString();
130
    
131
    /** Get full version string with build info */
132
    public String getFullVersion();
133
}
134
```
135

136
**Usage Examples:**
137

138
```java
139
public class VersionHandling {
140
    public void handleVersions() {
141
        // Get current version
142
        Version current = Version.getCurrent();
143
        System.out.println("Running on: " + current.toString());
144
        
145
        // Create and compare versions
146
        Version required = Version.create(21, 0, 0);
147
        Version latest = Version.parse("21.3.1-dev");
148
        
149
        if (current.isAtLeast(required)) {
150
            System.out.println("Version requirement satisfied");
151
        }
152
        
153
        if (latest.isSnapshot()) {
154
            System.out.println("Using development version");
155
        }
156
        
157
        // Version comparison
158
        if (current.compareTo(latest) < 0) {
159
            System.out.println("Newer version available: " + latest);
160
        }
161
        
162
        // Access version components
163
        System.out.println("Major: " + current.getMajor());
164
        System.out.println("Minor: " + current.getMinor());
165
        System.out.println("Patch: " + current.getPatch());
166
        
167
        if (current.getQualifier() != null) {
168
            System.out.println("Qualifier: " + current.getQualifier());
169
        }
170
    }
171
}
172
```
173

174
### Option Management System
175

176
Type-safe configuration system for languages and tools with validation and metadata.
177

178
```java { .api }
179
/**
180
 * Type-safe key for configuration options
181
 */
182
public final class OptionKey<T> {
183
    /** Get option value from option values */
184
    public T getValue(OptionValues values);
185
    
186
    /** Check if option has been explicitly set */
187
    public boolean hasBeenSet(OptionValues values);
188
    
189
    /** Get default value for this option */
190
    public T getDefaultValue();
191
    
192
    /** Get option type information */
193
    public OptionType<T> getType();
194
}
195

196
/**
197
 * Metadata describing a configuration option
198
 */
199
public final class OptionDescriptor {
200
    /** Create new option descriptor builder */
201
    public static OptionDescriptor.Builder newBuilder(OptionKey<?> key, String name);
202
    
203
    /** Get option name */
204
    public String getName();
205
    
206
    /** Get option key */
207
    public OptionKey<?> getKey();
208
    
209
    /** Get help text */
210
    public String getHelp();
211
    
212
    /** Get option category */
213
    public OptionCategory getCategory();
214
    
215
    /** Get option stability level */
216
    public OptionStability getStability();
217
    
218
    /** Check if option is deprecated */
219
    public boolean isDeprecated();
220
    
221
    /** Get deprecation message */
222
    public String getDeprecationMessage();
223
    
224
    /** Get allowed values if constrained */
225
    public Set<String> getAllowedValues();
226
}
227

228
/**
229
 * Builder for creating option descriptors
230
 */
231
public static final class OptionDescriptor.Builder {
232
    /** Set help text */
233
    public OptionDescriptor.Builder help(String help);
234
    
235
    /** Set option category */
236
    public OptionDescriptor.Builder category(OptionCategory category);
237
    
238
    /** Set stability level */
239
    public OptionDescriptor.Builder stability(OptionStability stability);
240
    
241
    /** Mark as deprecated with message */
242
    public OptionDescriptor.Builder deprecated(String message);
243
    
244
    /** Set allowed values */
245
    public OptionDescriptor.Builder allowedValues(String... values);
246
    
247
    /** Build option descriptor */
248
    public OptionDescriptor build();
249
}
250
```
251

252
**Usage Examples:**
253

254
```java
255
import org.graalvm.options.*;
256

257
public class OptionManagement {
258
    // Define option keys
259
    public static final OptionKey<Integer> MAX_ITERATIONS = 
260
        new OptionKey<>(100);
261
    
262
    public static final OptionKey<String> OUTPUT_FORMAT = 
263
        new OptionKey<>("json");
264
    
265
    public static final OptionKey<Boolean> ENABLE_PROFILING = 
266
        new OptionKey<>(false);
267
    
268
    public void demonstrateOptions() {
269
        // Create option descriptors
270
        OptionDescriptor maxIterDesc = OptionDescriptor
271
            .newBuilder(MAX_ITERATIONS, "max-iterations")
272
            .help("Maximum number of optimization iterations")
273
            .category(OptionCategory.USER)
274
            .stability(OptionStability.STABLE)
275
            .build();
276
        
277
        OptionDescriptor formatDesc = OptionDescriptor
278
            .newBuilder(OUTPUT_FORMAT, "output-format")
279
            .help("Output format for results")
280
            .category(OptionCategory.USER)
281
            .allowedValues("json", "xml", "text")
282
            .build();
283
        
284
        // Use with option values (context-dependent)
285
        OptionValues values = getOptionValues(); // Implementation-specific
286
        
287
        int maxIter = MAX_ITERATIONS.getValue(values);
288
        String format = OUTPUT_FORMAT.getValue(values);
289
        boolean profiling = ENABLE_PROFILING.getValue(values);
290
        
291
        // Check if explicitly set
292
        if (MAX_ITERATIONS.hasBeenSet(values)) {
293
            System.out.println("Max iterations explicitly set to: " + maxIter);
294
        } else {
295
            System.out.println("Using default max iterations: " + maxIter);
296
        }
297
    }
298
    
299
    // Placeholder for getting option values
300
    private OptionValues getOptionValues() {
301
        return null; // Implementation depends on context
302
    }
303
}
304
```
305

306
### Option Collections
307

308
Collections for managing groups of options with iteration and lookup capabilities.
309

310
```java { .api }
311
/**
312
 * Read-only access to option values
313
 */
314
public interface OptionValues {
315
    /** Get value for option key */
316
    <T> T get(OptionKey<T> optionKey);
317
    
318
    /** Check if option has been explicitly set */
319
    boolean hasBeenSet(OptionKey<?> optionKey);
320
    
321
    /** Get all option descriptors */
322
    OptionDescriptors getDescriptors();
323
}
324

325
/**
326
 * Collection of option descriptors with fast lookup
327
 */
328
public interface OptionDescriptors extends Iterable<OptionDescriptor> {
329
    /** Get descriptor by option name */
330
    OptionDescriptor get(String optionName);
331
    
332
    /** Check if option exists */
333
    boolean contains(String optionName);
334
    
335
    /** Get number of options */
336
    int size();
337
    
338
    /** Get iterator over all descriptors */
339
    Iterator<OptionDescriptor> iterator();
340
    
341
    /** Create empty option descriptors */
342
    static OptionDescriptors empty();
343
    
344
    /** Create from array of descriptors */
345
    static OptionDescriptors create(OptionDescriptor... descriptors);
346
    
347
    /** Create from list of descriptors */
348
    static OptionDescriptors create(List<OptionDescriptor> descriptors);
349
}
350

351
/**
352
 * Mutable map of option values
353
 */
354
public final class OptionMap {
355
    /** Create empty option map */
356
    public static OptionMap create();
357
    
358
    /** Put option value */
359
    public <T> void put(OptionKey<T> key, T value);
360
    
361
    /** Get option value */
362
    public <T> T get(OptionKey<T> key);
363
    
364
    /** Check if option is set */
365
    public boolean hasBeenSet(OptionKey<?> key);
366
    
367
    /** Remove option */
368
    public <T> T remove(OptionKey<T> key);
369
    
370
    /** Check if map is empty */
371
    public boolean isEmpty();
372
    
373
    /** Get number of options */
374
    public int size();
375
    
376
    /** Clear all options */
377
    public void clear();
378
    
379
    /** Convert to option values */
380
    public OptionValues asOptionValues();
381
}
382
```
383

384
**Usage Examples:**
385

386
```java
387
public class OptionCollections {
388
    public void manageOptionCollections() {
389
        // Create option map
390
        OptionMap options = OptionMap.create();
391
        options.put(MAX_ITERATIONS, 200);
392
        options.put(OUTPUT_FORMAT, "xml");
393
        options.put(ENABLE_PROFILING, true);
394
        
395
        // Check values
396
        if (options.hasBeenSet(MAX_ITERATIONS)) {
397
            int iterations = options.get(MAX_ITERATIONS);
398
            System.out.println("Iterations: " + iterations);
399
        }
400
        
401
        // Create descriptors collection
402
        List<OptionDescriptor> descriptorList = Arrays.asList(
403
            OptionDescriptor.newBuilder(MAX_ITERATIONS, "max-iterations")
404
                .help("Maximum iterations")
405
                .category(OptionCategory.USER)
406
                .build(),
407
            OptionDescriptor.newBuilder(OUTPUT_FORMAT, "output-format")
408
                .help("Output format")
409
                .category(OptionCategory.USER)
410
                .build()
411
        );
412
        
413
        OptionDescriptors descriptors = OptionDescriptors.create(descriptorList);
414
        
415
        // Iterate over descriptors
416
        for (OptionDescriptor desc : descriptors) {
417
            System.out.println("Option: " + desc.getName() + 
418
                             " - " + desc.getHelp());
419
        }
420
        
421
        // Lookup specific descriptor
422
        OptionDescriptor formatDesc = descriptors.get("output-format");
423
        if (formatDesc != null) {
424
            System.out.println("Found format option: " + formatDesc.getHelp());
425
        }
426
    }
427
}
428
```
429

430
### Option Types and Validation
431

432
Type system for option values with validation and conversion support.
433

434
```java { .api }
435
/**
436
 * Type specification for option values with validation
437
 */
438
public final class OptionType<T> {
439
    /** Create default type for given class */
440
    public static <T> OptionType<T> defaultType(Class<T> clazz);
441
    
442
    /** Create user-defined type with validation */
443
    public static <T> OptionType<T> user(Class<T> clazz, Function<String, T> converter);
444
    
445
    /** Create user type with validation and constraints */
446
    public static <T> OptionType<T> user(Class<T> clazz, 
447
                                        Function<String, T> converter,
448
                                        Predicate<T> validator);
449
    
450
    /** Get the option value type class */
451
    public Class<T> getType();
452
    
453
    /** Convert string to typed value */
454
    public T convert(String value);
455
    
456
    /** Validate typed value */
457
    public boolean isValid(T value);
458
    
459
    /** Get validation error message */
460
    public String getValidationError(T value);
461
}
462
```
463

464
**Usage Examples:**
465

466
```java
467
public class OptionTypes {
468
    public void defineCustomTypes() {
469
        // Custom integer type with range validation
470
        OptionType<Integer> positiveInt = OptionType.user(
471
            Integer.class,
472
            Integer::parseInt,
473
            value -> value > 0
474
        );
475
        
476
        // Custom enum type
477
        OptionType<LogLevel> logLevelType = OptionType.user(
478
            LogLevel.class,
479
            LogLevel::valueOf,
480
            value -> true
481
        );
482
        
483
        // File path type with existence validation
484
        OptionType<String> existingFile = OptionType.user(
485
            String.class,
486
            Function.identity(),
487
            path -> new File(path).exists()
488
        );
489
        
490
        // Use custom types in option keys
491
        OptionKey<Integer> threadCount = new OptionKey<>(
492
            1, // default value
493
            positiveInt
494
        );
495
        
496
        OptionKey<LogLevel> logLevel = new OptionKey<>(
497
            LogLevel.INFO,
498
            logLevelType
499
        );
500
    }
501
    
502
    enum LogLevel {
503
        ERROR, WARNING, INFO, DEBUG
504
    }
505
}
506
```
507

508
## Types
509

510
```java { .api }
511
// Option categorization
512
public enum OptionCategory {
513
    /** User-facing options visible in help */
514
    USER,
515
    
516
    /** Expert-level options for advanced users */
517
    EXPERT,
518
    
519
    /** Debug options for development */
520
    DEBUG
521
}
522

523
// API stability levels
524
public enum OptionStability {
525
    /** Stable API, safe for production use */
526
    STABLE,
527
    
528
    /** Experimental API, may change */
529
    EXPERIMENTAL
530
}
531

532
// Exception types
533
public class OptionException extends RuntimeException {
534
    public OptionException(String message);
535
    public OptionException(String message, Throwable cause);
536
}
537

538
public class OptionValidationException extends OptionException {
539
    public OptionValidationException(String optionName, String message);
540
    public String getOptionName();
541
}
542
```