0
# Code Generation
1

2
jsii-pacmak is a comprehensive code generation framework that creates native language bindings from jsii assemblies. It supports generating idiomatic libraries for Python, Java, .NET, Go, and JavaScript from a single TypeScript codebase.
3

4
## Capabilities
5

6
### Main Pacmak Function
7

8
The primary entry point for generating target language bindings with comprehensive configuration options.
9

10
```typescript { .api }
11
/**
12
 * Generate target language bindings from jsii assemblies
13
 * @param options Configuration for code generation
14
 * @returns Promise that resolves when generation completes
15
 */
16
function pacmak(options: PacmakOptions): Promise<void>;
17

18
/**
19
 * Configuration options for pacmak code generation
20
 */
21
interface PacmakOptions {
22
  /** Assembly file paths to process */
23
  assemblies: string[];
24
  /** Target languages to generate */
25
  targets: TargetName[];
26
  /** Output directory for generated code */
27
  outdir: string;
28
  /** Generate fingerprints for outputs */
29
  fingerprint?: boolean;
30
  /** Force regeneration of existing files */
31
  force?: boolean;
32
  /** Whether to validate generated code */
33
  validate?: boolean;
34
  /** Parallel generation jobs */
35
  parallel?: number;
36
  /** Arguments for specific target builders */
37
  arguments?: { [target: string]: { [key: string]: any } };
38
  /** Code examples directory */
39
  rosetta?: {
40
    /** Rosetta cache directory */
41
    cacheDir?: string;
42
    /** Example source directories */
43
    exampleDirs?: string[];
44
    /** Loose mode for examples */
45
    loose?: boolean;
46
  };
47
}
48
```
49

50
### Target Languages
51

52
Enumeration and configuration for all supported target language generators.
53

54
```typescript { .api }
55
/**
56
 * Supported target language names
57
 */
58
enum TargetName {
59
  /** .NET/C# bindings */
60
  DOTNET = "dotnet",
61
  /** Go bindings */
62
  GO = "go",
63
  /** Java bindings */
64
  JAVA = "java", 
65
  /** JavaScript/TypeScript bindings */
66
  JAVASCRIPT = "js",
67
  /** Python bindings */
68
  PYTHON = "python"
69
}
70

71
/**
72
 * Factory function for creating target builders
73
 */
74
type BuilderFactory = (options: any) => TargetBuilder;
75

76
/**
77
 * Map of all available target builders
78
 */
79
const ALL_BUILDERS: { [target in TargetName]: BuilderFactory };
80

81
/**
82
 * Base interface for target language builders
83
 */
84
interface TargetBuilder {
85
  /** Generate code for the target language */
86
  build(): Promise<void>;
87
  
88
  /** Target language name */
89
  readonly targetName: TargetName;
90
  
91
  /** Output directory */
92
  readonly outputDir: string;
93
}
94
```
95

96
### Python Target
97

98
Python-specific code generation with pip package creation and idiomatic Python APIs.
99

100
```typescript { .api }
101
/**
102
 * Python target configuration options
103
 */
104
interface PythonTargetOptions {
105
  /** Python package distribution name */
106
  distName?: string;
107
  /** Python module name */  
108
  module?: string;
109
  /** PyPI classifiers */
110
  classifiers?: string[];
111
  /** Package description */
112
  description?: string;
113
  /** Package homepage URL */
114
  homepage?: string;
115
  /** Author information */
116
  author?: {
117
    name?: string;
118
    email?: string;
119
  };
120
  /** Package license */
121
  license?: string;
122
  /** Additional package data */
123
  data?: { [path: string]: string[] };
124
}
125

126
/**
127
 * Python package generation builder
128
 */
129
class PythonBuilder implements TargetBuilder {
130
  readonly targetName = TargetName.PYTHON;
131
  readonly outputDir: string;
132

133
  /**
134
   * Create Python builder
135
   * @param assembly jsii assembly to process
136
   * @param options Python generation options
137
   */
138
  constructor(assembly: Assembly, options: PythonTargetOptions);
139

140
  /**
141
   * Generate Python package
142
   */
143
  build(): Promise<void>;
144
}
145
```
146

147
### Java Target  
148

149
Java-specific code generation with Maven artifact creation and Java-idiomatic APIs.
150

151
```typescript { .api }
152
/**
153
 * Java target configuration options
154
 */
155
interface JavaTargetOptions {
156
  /** Java package name */
157
  package?: string;
158
  /** Maven configuration */
159
  maven?: {
160
    /** Maven group ID */
161
    groupId?: string;
162
    /** Maven artifact ID */
163
    artifactId?: string;
164
    /** Maven version */
165
    version?: string;
166
    /** Additional dependencies */
167
    dependencies?: Array<{
168
      groupId: string;
169
      artifactId: string;
170
      version: string;
171
      scope?: string;
172
    }>;
173
  };
174
  /** Package description */
175
  description?: string;
176
  /** Package URL */
177
  url?: string;
178
}
179

180
/**
181
 * Java package generation builder
182
 */
183
class JavaBuilder implements TargetBuilder {
184
  readonly targetName = TargetName.JAVA;
185
  readonly outputDir: string;
186

187
  /**
188
   * Create Java builder
189
   * @param assembly jsii assembly to process
190
   * @param options Java generation options
191
   */
192
  constructor(assembly: Assembly, options: JavaTargetOptions);
193

194
  /**
195
   * Generate Java Maven project
196
   */
197
  build(): Promise<void>;
198
}
199
```
200

201
### .NET Target
202

203
.NET/C# code generation with NuGet package creation and C#-idiomatic APIs.
204

205
```typescript { .api }
206
/**
207
 * .NET target configuration options
208
 */
209
interface DotNetTargetOptions {
210
  /** .NET namespace */
211
  namespace?: string;
212
  /** NuGet package ID */
213
  packageId?: string;
214
  /** Package title */
215
  title?: string;
216
  /** Package description */
217
  description?: string;
218
  /** Package version */
219
  version?: string;
220
  /** Package authors */
221
  authors?: string[];
222
  /** Company name */
223
  company?: string;
224
  /** Package icon URL */
225
  iconUrl?: string;
226
  /** Strong naming key file */
227
  signAssembly?: boolean;
228
  /** Assembly key file path */
229
  assemblyOriginatorKeyFile?: string;
230
}
231

232
/**
233
 * .NET package generation builder
234
 */
235
class DotNetBuilder implements TargetBuilder {
236
  readonly targetName = TargetName.DOTNET;
237
  readonly outputDir: string;
238

239
  /**
240
   * Create .NET builder
241
   * @param assembly jsii assembly to process
242
   * @param options .NET generation options
243
   */
244
  constructor(assembly: Assembly, options: DotNetTargetOptions);
245

246
  /**
247
   * Generate .NET/C# project
248
   */
249
  build(): Promise<void>;
250
}
251
```
252

253
### Go Target
254

255
Go-specific code generation with Go module creation and Go-idiomatic APIs.
256

257
```typescript { .api }
258
/**
259
 * Go target configuration options
260
 */
261
interface GoTargetOptions {
262
  /** Go module name */
263
  moduleName?: string;
264
  /** Go package name */
265
  packageName?: string;
266
  /** Package description */ 
267
  description?: string;
268
  /** Package version */
269
  version?: string;
270
  /** Git tag prefix */
271
  gitTagPrefix?: string;
272
  /** Go version constraint */
273
  goVersion?: string;
274
}
275

276
/**
277
 * Go package generation builder
278
 */
279
class GoBuilder implements TargetBuilder {
280
  readonly targetName = TargetName.GO;
281
  readonly outputDir: string;
282

283
  /**
284
   * Create Go builder
285
   * @param assembly jsii assembly to process
286
   * @param options Go generation options
287
   */
288
  constructor(assembly: Assembly, options: GoTargetOptions);
289

290
  /**
291
   * Generate Go module
292
   */
293
  build(): Promise<void>;
294
}
295
```
296

297
### JavaScript Target
298

299
JavaScript/TypeScript code generation for creating npm packages with native TypeScript support.
300

301
```typescript { .api }
302
/**
303
 * JavaScript target configuration options
304
 */
305
interface JavaScriptTargetOptions {
306
  /** npm package name */
307
  npm?: string;
308
  /** Package description */
309
  description?: string;
310
  /** Package homepage */
311
  homepage?: string;
312
  /** Package repository */
313
  repository?: {
314
    type?: string;
315
    url?: string;
316
  };
317
  /** Package keywords */
318
  keywords?: string[];
319
  /** Package author */
320
  author?: string | {
321
    name?: string;
322
    email?: string;
323
    url?: string;
324
  };
325
}
326

327
/**
328
 * JavaScript package generation builder
329
 */
330
class JavaScriptBuilder implements TargetBuilder {
331
  readonly targetName = TargetName.JAVASCRIPT;
332
  readonly outputDir: string;
333

334
  /**
335
   * Create JavaScript builder
336
   * @param assembly jsii assembly to process
337
   * @param options JavaScript generation options
338
   */
339
  constructor(assembly: Assembly, options: JavaScriptTargetOptions);
340

341
  /**
342
   * Generate JavaScript/TypeScript npm package
343
   */
344
  build(): Promise<void>;
345
}
346
```
347

348
### Code Generation Utilities
349

350
Helper functions and utilities for the code generation process.
351

352
```typescript { .api }
353
/**
354
 * Configure logging for pacmak operations
355
 * @param level Log level (error, warn, info, debug)
356
 * @param format Log format options
357
 */
358
function configureLogging(level: string, format?: {
359
  colors?: boolean;
360
  timestamp?: boolean;
361
}): void;
362

363
/**
364
 * Disclaimer text for non-compiling generated examples
365
 */
366
const INCOMPLETE_DISCLAIMER_NONCOMPILING: string;
367

368
/**
369
 * Validate target configuration
370
 * @param target Target name to validate
371
 * @param options Target-specific options
372
 * @returns Validation result
373
 */
374
function validateTargetOptions(
375
  target: TargetName, 
376
  options: any
377
): { valid: boolean; errors?: string[] };
378

379
/**
380
 * Get default output directory for target
381
 * @param target Target language
382
 * @param baseDir Base output directory
383
 * @returns Target-specific output path
384
 */
385
function getTargetOutputDir(target: TargetName, baseDir: string): string;
386

387
/**
388
 * Generate code examples using Rosetta
389
 * @param assembly jsii assembly
390
 * @param target Target language
391
 * @param options Rosetta options
392
 */
393
function generateExamples(
394
  assembly: Assembly,
395
  target: TargetName, 
396
  options?: {
397
    strict?: boolean;
398
    cacheDir?: string;
399
  }
400
): Promise<{ [exampleId: string]: string }>;
401
```
402

403
### Assembly Processing
404

405
Functions for loading and processing jsii assemblies during code generation.
406

407
```typescript { .api }
408
/**
409
 * Load assemblies for code generation
410
 * @param assemblyPaths Paths to assembly files
411
 * @returns Loaded assemblies with dependencies
412
 */
413
function loadAssemblies(assemblyPaths: string[]): Assembly[];
414

415
/**
416
 * Resolve assembly dependencies
417
 * @param assemblies Primary assemblies
418
 * @returns All assemblies including dependencies
419
 */
420
function resolveDependencies(assemblies: Assembly[]): Assembly[];
421

422
/**
423
 * Validate assemblies for code generation
424
 * @param assemblies Assemblies to validate
425
 * @returns Validation results
426
 */
427
function validateAssemblies(assemblies: Assembly[]): {
428
  valid: boolean;
429
  errors: Array<{
430
    assembly: string;
431
    message: string;
432
  }>;
433
};
434

435
/**
436
 * Extract metadata from assembly for target generation
437
 * @param assembly jsii assembly
438
 * @param target Target language
439
 * @returns Target-specific metadata
440
 */
441
function extractTargetMetadata(
442
  assembly: Assembly,
443
  target: TargetName
444
): { [key: string]: any };
445
```
446

447
## Types
448

449
```typescript { .api }
450
/**
451
 * Assembly loaded for code generation
452
 */
453
interface Assembly {
454
  /** Assembly specification */
455
  spec: import('@jsii/spec').Assembly;
456
  /** Assembly metadata */
457
  metadata: { [key: string]: any };
458
  /** Assembly file path */
459
  path: string;
460
  /** Loaded dependencies */
461
  dependencies: Assembly[];
462
}
463

464
/**
465
 * Code generation context
466
 */
467
interface GenerationContext {
468
  /** Current assembly */
469
  assembly: Assembly;
470
  /** Target language */
471
  target: TargetName;
472
  /** Output directory */
473
  outputDir: string;
474
  /** Generation options */
475
  options: any;
476
  /** Example snippets */
477
  examples?: { [id: string]: string };
478
}
479

480
/**
481
 * Generated file information
482
 */
483
interface GeneratedFile {
484
  /** Relative file path */
485
  path: string;
486
  /** File content */
487
  content: string;
488
  /** File permissions */
489
  permissions?: number;
490
  /** Whether file is executable */
491
  executable?: boolean;
492
}
493

494
/**
495
 * Generation result
496
 */
497
interface GenerationResult {
498
  /** Generated files */
499
  files: GeneratedFile[];
500
  /** Generation warnings */
501
  warnings?: string[];
502
  /** Generation metadata */
503
  metadata?: { [key: string]: any };
504
}
505
```
506

507
**Usage Examples:**
508

509
```typescript
510
// Basic code generation for multiple targets
511
import { pacmak, TargetName } from 'jsii-pacmak';
512

513
await pacmak({
514
  assemblies: ['./lib/my-library/.jsii'],
515
  targets: [TargetName.PYTHON, TargetName.JAVA, TargetName.DOTNET],
516
  outdir: './dist'
517
});
518

519
// Advanced configuration with target-specific options
520
await pacmak({
521
  assemblies: ['./lib/my-library/.jsii'],
522
  targets: [TargetName.PYTHON, TargetName.JAVA],
523
  outdir: './packages',
524
  arguments: {
525
    python: {
526
      distName: 'my-awesome-library',
527
      classifiers: [
528
        'Development Status :: 5 - Production/Stable',
529
        'Programming Language :: Python :: 3.8'
530
      ]
531
    },
532
    java: {
533
      maven: {
534
        groupId: 'com.example',
535
        artifactId: 'my-library'
536
      }
537
    }
538
  },
539
  rosetta: {
540
    cacheDir: './rosetta-cache',
541
    exampleDirs: ['./examples']
542
  }
543
});
544

545
// Generate single target with validation
546
import { configureLogging } from 'jsii-pacmak';
547

548
configureLogging('info', { colors: true });
549

550
await pacmak({
551
  assemblies: ['./lib/my-library/.jsii'],
552
  targets: [TargetName.GO],
553
  outdir: './go-bindings',
554
  validate: true,
555
  arguments: {
556
    go: {
557
      moduleName: 'github.com/example/my-library-go',
558
      goVersion: '1.19'
559
    }
560
  }
561
});
562
```