Skip to content

Commit 6e1c63c

Browse files
ayersdeckerayersdecker
committed
All tests passed, ready for impl.
1 parent 79da5f9 commit 6e1c63c

29 files changed

Lines changed: 1672 additions & 18 deletions

‎.editorconfig‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# EditorConfig is awesome: https://EditorConfig.org
2+
3+
# top-most EditorConfig file
4+
root = true
5+
6+
# All files
7+
[*]
8+
charset = utf-8
9+
insert_final_newline = true
10+
trim_trailing_whitespace = true
11+
12+
# Code files
13+
[*.{cs,csx,vb,vbx}]
14+
indent_size = 4
15+
indent_style = space
16+
tab_width = 4
17+
18+
# XML project files
19+
[*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj}]
20+
indent_size = 2
21+
22+
# XML config and MAUI files
23+
[*.{props,targets,ruleset,config,nuspec,resx,vsixmanifest,xaml}]
24+
indent_size = 2
25+
26+
# JSON files
27+
[*.json]
28+
indent_size = 2
29+
30+
# YAML files
31+
[*.{yml,yaml}]
32+
indent_size = 2
33+
34+
# Shell scripts
35+
[*.sh]
36+
end_of_line = lf
37+
indent_size = 2
38+
39+
# PowerShell scripts
40+
[*.ps1]
41+
indent_size = 4
42+
43+
# Markdown files
44+
[*.md]
45+
trim_trailing_whitespace = false
46+
47+
# CMake files
48+
[{CMakeLists.txt,*.cmake}]
49+
indent_size = 4
50+
51+
# C/C++ files
52+
[*.{c,cpp,h,hpp}]
53+
indent_size = 4
54+
indent_style = space
55+
56+
# .NET Coding Conventions
57+
[*.{cs,vb}]
58+
59+
# Organize usings
60+
dotnet_sort_system_directives_first = true
61+
dotnet_separate_import_directive_groups = false
62+
63+
# this. preferences
64+
dotnet_style_qualification_for_field = false:suggestion
65+
dotnet_style_qualification_for_property = false:suggestion
66+
dotnet_style_qualification_for_method = false:suggestion
67+
dotnet_style_qualification_for_event = false:suggestion
68+
69+
# Language keywords vs framework type names for type references
70+
dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
71+
dotnet_style_predefined_type_for_member_access = true:suggestion
72+
73+
# Parentheses preferences
74+
dotnet_style_parentheses_in_arithmetic_binary_operators = always_for_clarity:suggestion
75+
dotnet_style_parentheses_in_relational_binary_operators = always_for_clarity:suggestion
76+
dotnet_style_parentheses_in_other_binary_operators = always_for_clarity:suggestion
77+
dotnet_style_parentheses_in_other_operators = never_if_unnecessary:suggestion
78+
79+
# Modifier preferences
80+
dotnet_style_require_accessibility_modifiers = for_non_interface_members:suggestion
81+
dotnet_style_readonly_field = true:suggestion
82+
83+
# Expression-level preferences
84+
dotnet_style_object_initializer = true:suggestion
85+
dotnet_style_collection_initializer = true:suggestion
86+
dotnet_style_explicit_tuple_names = true:suggestion
87+
dotnet_style_prefer_inferred_tuple_names = true:suggestion
88+
dotnet_style_prefer_inferred_anonymous_type_member_names = true:suggestion
89+
dotnet_style_prefer_auto_properties = true:suggestion
90+
dotnet_style_prefer_conditional_expression_over_assignment = true:silent
91+
dotnet_style_prefer_conditional_expression_over_return = true:silent
92+
dotnet_style_prefer_compound_assignment = true:suggestion
93+
94+
# Null-checking preferences
95+
dotnet_style_coalesce_expression = true:suggestion
96+
dotnet_style_null_propagation = true:suggestion
97+
dotnet_style_prefer_is_null_check_over_reference_equality_method = true:suggestion
98+
99+
# C# Coding Conventions
100+
[*.cs]
101+
102+
# var preferences
103+
csharp_style_var_for_built_in_types = false:suggestion
104+
csharp_style_var_when_type_is_apparent = true:suggestion
105+
csharp_style_var_elsewhere = false:suggestion
106+
107+
# Expression-bodied members
108+
csharp_style_expression_bodied_methods = false:suggestion
109+
csharp_style_expression_bodied_constructors = false:suggestion
110+
csharp_style_expression_bodied_operators = false:suggestion
111+
csharp_style_expression_bodied_properties = true:suggestion
112+
csharp_style_expression_bodied_indexers = true:suggestion
113+
csharp_style_expression_bodied_accessors = true:suggestion
114+
csharp_style_expression_bodied_lambdas = true:suggestion
115+
csharp_style_expression_bodied_local_functions = false:suggestion
116+
117+
# Pattern matching preferences
118+
csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
119+
csharp_style_pattern_matching_over_as_with_null_check = true:suggestion
120+
csharp_style_prefer_switch_expression = true:suggestion
121+
csharp_style_prefer_pattern_matching = true:suggestion
122+
csharp_style_prefer_not_pattern = true:suggestion
123+
124+
# Null-checking preferences
125+
csharp_style_throw_expression = true:suggestion
126+
csharp_style_conditional_delegate_call = true:suggestion
127+
128+
# Modifier preferences
129+
csharp_prefer_static_local_function = true:suggestion
130+
csharp_preferred_modifier_order = public,private,protected,internal,static,extern,new,virtual,abstract,sealed,override,readonly,unsafe,volatile,async:suggestion
131+
132+
# Code-block preferences
133+
csharp_prefer_braces = true:suggestion
134+
csharp_prefer_simple_using_statement = true:suggestion
135+
136+
# Expression-level preferences
137+
csharp_prefer_simple_default_expression = true:suggestion
138+
csharp_style_pattern_local_over_anonymous_function = true:suggestion
139+
csharp_style_inlined_variable_declaration = true:suggestion
140+
csharp_style_deconstructed_variable_declaration = true:suggestion
141+
142+
# C# Formatting Rules
143+
[*.cs]
144+
145+
# New line preferences
146+
csharp_new_line_before_open_brace = all
147+
csharp_new_line_before_else = true
148+
csharp_new_line_before_catch = true
149+
csharp_new_line_before_finally = true
150+
csharp_new_line_before_members_in_object_initializers = true
151+
csharp_new_line_before_members_in_anonymous_types = true
152+
csharp_new_line_between_query_expression_clauses = true
153+
154+
# Indentation preferences
155+
csharp_indent_case_contents = true
156+
csharp_indent_switch_labels = true
157+
csharp_indent_labels = no_change
158+
csharp_indent_block_contents = true
159+
csharp_indent_braces = false
160+
csharp_indent_case_contents_when_block = false
161+
162+
# Space preferences
163+
csharp_space_after_cast = false
164+
csharp_space_after_keywords_in_control_flow_statements = true
165+
csharp_space_between_parentheses = false
166+
csharp_space_before_colon_in_inheritance_clause = true
167+
csharp_space_after_colon_in_inheritance_clause = true
168+
csharp_space_around_binary_operators = before_and_after
169+
csharp_space_between_method_declaration_parameter_list_parentheses = false
170+
csharp_space_between_method_declaration_empty_parameter_list_parentheses = false
171+
csharp_space_between_method_declaration_name_and_open_parenthesis = false
172+
csharp_space_between_method_call_parameter_list_parentheses = false
173+
csharp_space_between_method_call_empty_parameter_list_parentheses = false
174+
csharp_space_between_method_call_name_and_opening_parenthesis = false
175+
csharp_space_after_comma = true
176+
csharp_space_after_dot = false
177+
csharp_space_after_semicolon_in_for_statement = true
178+
csharp_space_before_semicolon_in_for_statement = false
179+
csharp_space_around_declaration_statements = false
180+
csharp_space_before_open_square_brackets = false
181+
csharp_space_between_empty_square_brackets = false
182+
csharp_space_between_square_brackets = false
183+
184+
# Wrapping preferences
185+
csharp_preserve_single_line_statements = false
186+
csharp_preserve_single_line_blocks = true
187+
188+
# Naming Conventions
189+
190+
# Constant fields are PascalCase
191+
dotnet_naming_rule.constant_fields_should_be_pascal_case.severity = suggestion
192+
dotnet_naming_rule.constant_fields_should_be_pascal_case.symbols = constant_fields
193+
dotnet_naming_rule.constant_fields_should_be_pascal_case.style = pascal_case_style
194+
dotnet_naming_symbols.constant_fields.applicable_kinds = field
195+
dotnet_naming_symbols.constant_fields.applicable_accessibilities = *
196+
dotnet_naming_symbols.constant_fields.required_modifiers = const
197+
dotnet_naming_style.pascal_case_style.capitalization = pascal_case
198+
199+
# Static fields are PascalCase
200+
dotnet_naming_rule.static_fields_should_be_pascal_case.severity = suggestion
201+
dotnet_naming_rule.static_fields_should_be_pascal_case.symbols = static_fields
202+
dotnet_naming_rule.static_fields_should_be_pascal_case.style = pascal_case_style
203+
dotnet_naming_symbols.static_fields.applicable_kinds = field
204+
dotnet_naming_symbols.static_fields.applicable_accessibilities = *
205+
dotnet_naming_symbols.static_fields.required_modifiers = static
206+
207+
# Private fields are _camelCase
208+
dotnet_naming_rule.private_fields_should_be_camel_case_with_underscore.severity = suggestion
209+
dotnet_naming_rule.private_fields_should_be_camel_case_with_underscore.symbols = private_fields
210+
dotnet_naming_rule.private_fields_should_be_camel_case_with_underscore.style = camel_case_underscore_style
211+
dotnet_naming_symbols.private_fields.applicable_kinds = field
212+
dotnet_naming_symbols.private_fields.applicable_accessibilities = private
213+
dotnet_naming_style.camel_case_underscore_style.required_prefix = _
214+
dotnet_naming_style.camel_case_underscore_style.capitalization = camel_case
215+
216+
# Locals and parameters are camelCase
217+
dotnet_naming_rule.locals_should_be_camel_case.severity = suggestion
218+
dotnet_naming_rule.locals_should_be_camel_case.symbols = locals_and_parameters
219+
dotnet_naming_rule.locals_should_be_camel_case.style = camel_case_style
220+
dotnet_naming_symbols.locals_and_parameters.applicable_kinds = parameter, local
221+
dotnet_naming_style.camel_case_style.capitalization = camel_case
222+
223+
# Local functions are PascalCase
224+
dotnet_naming_rule.local_functions_should_be_pascal_case.severity = suggestion
225+
dotnet_naming_rule.local_functions_should_be_pascal_case.symbols = local_functions
226+
dotnet_naming_rule.local_functions_should_be_pascal_case.style = pascal_case_style
227+
dotnet_naming_symbols.local_functions.applicable_kinds = local_function
228+
229+
# By default, name items with PascalCase
230+
dotnet_naming_rule.members_should_be_pascal_case.severity = suggestion
231+
dotnet_naming_rule.members_should_be_pascal_case.symbols = all_members
232+
dotnet_naming_rule.members_should_be_pascal_case.style = pascal_case_style
233+
dotnet_naming_symbols.all_members.applicable_kinds = *

‎CHANGELOG.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Changelog
2+
3+
All notable changes to Ferrum will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- Production-ready documentation and developer experience improvements
12+
- Comprehensive CONTRIBUTING.md with build, test, and PR guidelines
13+
- Detailed README for MinimalDemo sample
14+
- .editorconfig for consistent code formatting across contributors
15+
- `dotnet new` template (`maui-ferrum`) for scaffolding new projects
16+
- Troubleshooting section in main README
17+
- Roadmap section in main README
18+
- NuGet and CI badges in README
19+
20+
### Changed
21+
- Enhanced README with three quick-start options (template, sample, existing app)
22+
- Improved NuGet package metadata with README inclusion
23+
- Reorganized Quick Start section for better discoverability
24+
25+
### Fixed
26+
- NuGet packages now properly include README.md
27+
28+
## [0.1.0-alpha] - TBD
29+
30+
### Added
31+
- Initial alpha release
32+
- `Ferrum.Framework` NuGet package with `NativeBuffer<T>` for zero-copy interop
33+
- `ferrum-codegen` dotnet tool for generating `[LibraryImport]` bindings from C headers
34+
- NativeAOT-compatible P/Invoke using `[LibraryImport]` (source-generated)
35+
- CMake build scripts for iOS (XCFramework) and Android (.so per ABI)
36+
- MinimalDemo sample demonstrating end-to-end native interop
37+
- Cross-platform support for .NET 9 MAUI on iOS and Android
38+
- Blittable-only type system (loud failures on unsupported constructs)
39+
- xUnit test suite for framework and codegen validation
40+
- CI/CD workflows:
41+
- `codegen-tests.yml` - Runs xUnit tests for codegen tool
42+
- `native-build.yml` - Builds native libraries for iOS/Android
43+
- `maui-build.yml` - Builds MAUI sample project
44+
- Comprehensive documentation:
45+
- Architecture overview
46+
- Getting started guide
47+
- Open questions for architectural decisions
48+
49+
### Design Constraints
50+
- Framework-only (no domain-specific logic)
51+
- NativeAOT-first (no runtime codegen or reflection-based marshalling)
52+
- Loud failures (codegen exits non-zero rather than emitting incorrect bindings)
53+
- Blittable types only (1:1 memory layout between C and C#)
54+
55+
### Known Limitations (v0.1.0-alpha)
56+
- iOS and Android only (Windows/macOS desktop MAUI not supported)
57+
- Simple regex-based codegen parser (no libclang integration)
58+
- No official NuGet package publication yet (local build only)
59+
- Template must be installed locally from repository
60+
61+
---
62+
63+
## Release Guidelines (for maintainers)
64+
65+
### Pre-release Checklist
66+
- [ ] Update version in all `.csproj` files
67+
- [ ] Update CHANGELOG.md with release date
68+
- [ ] Run full test suite: `dotnet test`
69+
- [ ] Build NuGet packages: `dotnet pack --configuration Release`
70+
- [ ] Verify package contents
71+
- [ ] Test template installation and usage
72+
- [ ] Update README badges if needed
73+
- [ ] Create and push Git tag: `git tag v0.1.0-alpha && git push origin v0.1.0-alpha`
74+
75+
### Publishing
76+
```bash
77+
# Publish to NuGet.org
78+
dotnet nuget push artifacts/packages/Ferrum.Framework.*.nupkg --api-key YOUR_KEY --source https://api.nuget.org/v3/index.json
79+
dotnet nuget push artifacts/packages/Ferrum.Codegen.*.nupkg --api-key YOUR_KEY --source https://api.nuget.org/v3/index.json
80+
81+
# Optional: Publish template (when packaged)
82+
dotnet nuget push artifacts/packages/Ferrum.Templates.*.nupkg --api-key YOUR_KEY --source https://api.nuget.org/v3/index.json
83+
```
84+
85+
### Versioning Strategy
86+
- **0.x.y**: Pre-1.0 releases, breaking changes allowed in minor versions
87+
- **1.x.y**: Stable releases, breaking changes require major version bump
88+
- **x.y.z-alpha/beta/rc**: Pre-release tags for testing
89+
90+
---
91+
92+
[Unreleased]: https://github.com/ayersdecker/ferrum/compare/v0.1.0-alpha...HEAD
93+
[0.1.0-alpha]: https://github.com/ayersdecker/ferrum/releases/tag/v0.1.0-alpha

0 commit comments

Comments
 (0)