build/dev/lib/_pkg/sigil-build/project-file.md

1# Package File Reference

3> Configuration for Sigil packages and workspaces.

5The `package.sgl` file defines package metadata, dependencies, and build configuration.

7## File Extension

9Package files must be named `package.sgl` (not `package.sg` or other variants).

11## Package Definition

13A basic package:

15```scheme

16(package

17 name: "my-app"

18 version: "0.1.0"

19 description: "My application"

20 license: "MIT"

21 authors: (list "Your Name <[email protected]>")

23 source-dirs: '("src"))

24```

26### Required Fields

28- `name:` - Package name (string)

29- `version:` - Semantic version (string)

31### Optional Fields

33- `description:` - Short description

34- `license:` - License identifier (e.g., "MIT", "BSD-3-Clause")

35- `authors:` - List of author strings

36- `url:` - Repository URL

37- `source-dirs:` - Directories containing source files (default: `'("src")`)

39## Entry Point

41For executable applications, specify the entry module:

43```scheme

44(package

45 name: "my-cli"

46 version: "0.1.0"

47 description: "A command-line tool"

49 entry: '(my-cli main)

51 source-dirs: '("src"))

52```

The `entry:` field specifies the module that contains the application's `main` procedure. This is used when bundling the application into a standalone executable.

56## Dependencies

58### Workspace Dependencies

60Reference other packages in the same workspace:

62```scheme

63(package

64 name: "my-app"

65 version: "0.1.0"

67 dependencies: (list

68 (from-workspace name: "sigil-json")

69 (from-workspace name: "sigil-http"))

71 source-dirs: '("src"))

72```

74## Workspace Definition

76A workspace groups multiple packages together. The root `package.sgl` of a multi-package project:

78```scheme

79(workspace

80 name: "my-project"

81 version: "0.1.0"

82 description: "A multi-package project"

83 license: "MIT"

84 authors: (list "Your Name <[email protected]>")

86 packages: (list

87 "packages/my-lib"

88 "packages/my-app")

90 configs: (list

91 (config

92 name: 'dev

93 output-dir: "build/dev"

94 debug?: #t

95 optimize: 0)

97 (config

98 name: 'release

99 output-dir: "build/release"

100 static?: #t

101 optimize: 2))

102

103 default-config: 'dev)

104```

105

106### Workspace Fields

107

108- `packages:` - List of package directory paths

109- `configs:` - Build configurations

110- `default-config:` - Configuration used when none specified

111

112### Config Options

113

114| Option | Description |

115|--------|-------------|

116| `name:` | Configuration name (symbol) |

117| `output-dir:` | Build output directory |

118| `debug?:` | Include debug symbols |

119| `optimize:` | Optimization level (0-3) |

120| `static?:` | Enable static linking |

121| `toolchain:` | Toolchain to use (`'musl` for static builds) |

122

123## Running Your Application

124

125During development, run your application with:

126

127```bash

128# Run the main module

129sigil eval '(import (my-app main)) (main)'

130

131# Or run a file directly

132sigil eval -f src/my-app/main.sgl

133```

134

135To create a standalone executable:

136

137```bash

138sigil bundle my-app --config release

139```

140

141## File Location

142

143Sigil searches for `package.sgl` in:

1441. Current directory

1452. Parent directories (up to filesystem root)

146

147This allows running commands from subdirectories within a project.