Skip to content

Commit 1f7ba54

Browse files
danielmezadanielmeza
authored
Rework targets and props for SDK (#3)
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: José Simões <jose.simoes@eclo.solutions> ***NO_CI***
1 parent 722432a commit 1f7ba54

13 files changed

Lines changed: 984 additions & 482 deletions

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,10 +47,16 @@ Or pin the SDK version in `global.json`:
4747

4848
```
4949
src/
50-
nanoFramework.Sdk/ SDK NuGet package (Sdk.props / Sdk.targets)
50+
nanoFramework.NET.Sdk/ SDK NuGet package (Sdk.props / Sdk.targets)
5151
nanoFramework.Tools.BuildTasks/ Custom MSBuild tasks (resource gen, binary output, etc.)
5252
```
5353

54+
## Tools
55+
56+
The `dotnet nano` umbrella CLI and the `nano-migrate` project migrator (with the companion
57+
SDK-migration skill) live in the [nanoframework/nf-tools](https://github.com/nanoframework/nf-tools)
58+
repository, under `tools/nano` and `tools/migrate`.
59+
5460
## Development
5561

5662
```bash

‎SDK props and targets renaming.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# nanoFramework SDK — naming consistency pass
2+
3+
## Context
4+
5+
The new `nanoFramework.NET.Sdk` (on the `move-to-sdk` branch) carries its build logic in
6+
seven MSBuild files under [src/nanoFramework.NET.Sdk/Sdk/](src/nanoFramework.NET.Sdk/Sdk/).
7+
Those files accreted **four** different naming styles for symbols and properties:
8+
9+
- `_NfXxx` — underscore + the `Nf` abbreviation (internal paths)
10+
- `NanoXxx` — `Nano` PascalCase (the established public style)
11+
- `NanoFramework_Xxx` — `NanoFramework` + an underscore separator (unusual for MSBuild)
12+
- `NFMDP_XXX_Yyy` — SCREAMING_SNAKE with the `NF`/`MDP` abbreviations (carried over from the
13+
legacy NFProjectSystem targets)
14+
15+
Plus two casing slips: the target `MetaDataProcessor` (should be `Metadata`, one word) and two
16+
different names for the same concept — `IsCoreAssembly` and `NanoIsCoreLibrary`.
17+
18+
The goal is a single, descriptive, .NET-SDK-consistent convention without breaking anyone:
19+
20+
- **Public/user-settable properties:** `Nano` PascalCase prefix, no underscores, no SCREAMING_SNAKE.
21+
- **Internal/computed symbols:** leading-underscore `_Nano…` PascalCase (mirrors the .NET SDK's
22+
`_OutputPathWasMissing` / `_TargetFrameworkDirectories` style).
23+
- **Acronyms:** PascalCase per the .NET Framework Design Guidelines → `Tfm`, `Mdp`, `Pe`, `Dat`,
24+
`Xml`, `Pdbx`. (Matches the existing `nanoFramework.Tfm.props` filename.)
25+
- **Legacy user knobs:** rename to the new name **but keep the old name as a fallback alias** so
26+
existing `.csproj` files keep working.
27+
28+
All current references are confined to the seven `Sdk/` files (verified by repo-wide grep), so
29+
renames are local — except the external contracts listed in "Do NOT rename" below.
30+
31+
## Rename tables
32+
33+
### A. Internal SDK path properties (clean rename)
34+
35+
| Current | Proposed |
36+
|---|---|
37+
| `_NfSdkDir` | `_NanoSdkDir` |
38+
| `_NfSdkRoot` | `_NanoSdkRoot` |
39+
| `_NfSdkTasksDir` | `_NanoBuildTasksDir` (the SDK-bundled `BuildTasks.dll` dir — distinct from the MDP NuGet dir) |
40+
| `_NfMdpTasksTFM` | `_NanoMdpTasksTfm` |
41+
| `_NfMdpTasksDir` | `_NanoMdpTasksDir` |
42+
43+
### B. Internal pipeline props/items (drop the `NanoFramework_` underscore separator → `_Nano…`)
44+
45+
| Current | Proposed |
46+
|---|---|
47+
| `NanoFramework_StartProgram` | `_NanoStartProgram` |
48+
| `NanoFramework_IntermediateAssembly` | `_NanoIntermediateAssembly` |
49+
| `NanoFramework_Assembly` | `_NanoOutputAssembly` |
50+
| `@(NanoFramework_Resources)` | `@(_NanoResources)` |
51+
| `@(NanoFramework_StartProgram_ResolvedFiles)` | `@(_NanoStartProgramResolvedFiles)` |
52+
| `@(NanoFramework_StartProgram_ResolvedDependencyFiles)` | `@(_NanoStartProgramResolvedDependencyFiles)` |
53+
54+
### C. Legacy `NFMDP_*` symbols
55+
56+
**C1 — user-facing knobs → rename + alias** (see alias pattern below):
57+
58+
| Current | Proposed (primary) |
59+
|---|---|
60+
| `NFMDP_PE_Verbose` | `NanoMdpVerbose` |
61+
| `NFMDP_PE_VerboseMinimize` | `NanoMdpVerboseMinimize` |
62+
63+
**C2 — internal switches (driven by `NanoIsCoreLibrary`, core-assembly mechanics) → `_NanoMdp…`:**
64+
65+
| Current | Proposed |
66+
|---|---|
67+
| `NFMDP_GENERATE_PE` | `_NanoMdpGeneratePe` |
68+
| `NFMDP_DUMP_METADATA` | `_NanoMdpDumpMetadata` |
69+
| `NFMDP_GENERATE_STUBS` | `_NanoMdpGenerateStubs` |
70+
| `NFMDP_DAT_FILES` | `_NanoMdpGenerateDatFiles` |
71+
| `NFMDP_XML_FILES` | `_NanoMdpGenerateXmlFiles` |
72+
73+
**C3 — internal core-assembly path computations + stub params → `_NanoMdp…` / `_NanoMdpStub…`:**
74+
75+
| Current | Proposed |
76+
|---|---|
77+
| `NFMDP_PE_Parse` | `_NanoMdpParseInput` |
78+
| `NFMDP_PE_Compile` | `_NanoMdpCompileOutput` |
79+
| `NFMDP_PE_Compile_NoExt` | `_NanoMdpCompileOutputNoExt` |
80+
| `NFMDP_PE_SaveStrings` | `_NanoMdpSaveStringsFile` |
81+
| `NFMDP_PE_DumpExports` | `_NanoMdpDumpExportsFile` |
82+
| `NFMDP_PE_GenerateDependency` | `_NanoMdpDependencyMapFile` |
83+
| `@(NFMDP_PE_ExcludeClassByName)` | `@(_NanoMdpExcludeClassByName)` |
84+
| `@(NFMDP_PE_LoadHints)` | `@(_NanoMdpLoadHints)` |
85+
| `NFMDP_STUB_GenerateSkeletonProject` | `_NanoMdpStubSkeletonProject` |
86+
| `NFMDP_STUB_GenerateSkeletonName` | `_NanoMdpStubSkeletonName` |
87+
| `NFMDP_STUB_GenerateSkeletonFile` | `_NanoMdpStubSkeletonFile` |
88+
| `NFMDP_STUB_SkeletonWithoutInterop` | `_NanoMdpStubSkeletonWithoutInterop` |
89+
| `NFMDP_STUB_Resolve` | `_NanoMdpStubResolve` |
90+
| `NFMDP_STUB_DumpExports` *(referenced, never defined)* | `_NanoMdpStubDumpExports` |
91+
| `NFMDP_STUB_GenerateDependency` *(referenced, never defined)* | `_NanoMdpStubGenerateDependency` |
92+
93+
### D. Already-`Nano` public knobs — acronym/case tweaks (+ alias on the two renamed)
94+
95+
| Current | Proposed | Alias kept? |
96+
|---|---|---|
97+
| `NanoFrameworkMDPVersion` | `NanoMdpVersion` | yes |
98+
| `DisableNanoFrameworkMDP` | `DisableNanoMdp` | yes |
99+
| `NanoIsCoreLibrary` | unchanged | — |
100+
| `NanoGenerateStubsDirectory` / `…StubsRootName` / `…SkeletonProjectName` / `…SkeletonFile` | unchanged (already on-convention) | — |
101+
102+
`IsCoreAssembly` (Sdk.targets) and `NanoIsCoreLibrary` are the **same concept** (project builds
103+
mscorlib). Consolidate on `NanoIsCoreLibrary`; keep `IsCoreAssembly` as a fallback alias since the
104+
mscorlib build may set it externally.
105+
106+
### E. Target names → PascalCase, `Nano` namespace, `Metadata` casing fix
107+
108+
| Current | Proposed |
109+
|---|---|
110+
| `MetaDataProcessor` | `NanoMetadataProcessor` |
111+
| `MetaDataProcessorCompile` | `NanoMetadataProcessorCompile` |
112+
| `MetaDataProcessorDat` | `NanoMetadataProcessorDat` |
113+
| `MetaDataProcessorDependsOn` *(property)* | `NanoMetadataProcessorDependsOn` |
114+
| `NFMDP_CreateDatabaseAndDependencyMap` | `_NanoCreateDatabaseAndDependencyMap` |
115+
| `NanoFrameworkClean` | `NanoClean` |
116+
| `CopyToOutDir` | `_NanoCopyAssemblyToOutDir` |
117+
| `CopyNanoFrameworkFiles` | `NanoCopyOutputFiles` |
118+
| `CopyBackNanoFrameworkDlls` | `_NanoCopyReferencesToIntermediate` |
119+
| `NanoCLR_CleanExtraFiles` | `_NanoCleanExtraFiles` |
120+
| `NanoResourceGenerator` | `NanoGenerateResources` (verb-first, like MS `GenerateResource`) |
121+
| `NanoGenerateBinaryOutput` | unchanged |
122+
| `ResolveRuntimeDependencies` | unchanged (matches MS dependency-target style; referenced in `…DependsOn` chains) |
123+
124+
Each renamed target name must also be updated where it appears in the `*DependsOn` property
125+
chains and `<CallTarget>` calls (all within these same files).
126+
127+
### F. Do NOT rename (external / fixed contracts)
128+
129+
- **Env-var overrides** set by devs/CI: `NF_MSBUILDTASK_PATH`, `NF_MDP_MSBUILDTASK_PATH`.
130+
- **CI output variable** consumed by external pipelines: `NF_NATIVE_ASSEMBLY_CHECKSUM`
131+
(and the harness-provided `TF_BUILD`, `GITHUB_ACTIONS`, `GITHUB_ENV`).
132+
- **Compile `#if` symbols:** `NETNANO1_0`, `NANOFRAMEWORK_1_0`.
133+
- **VS CPS / debugger contract:** `NanoDebugger` (DebuggerFlavor + `Rules\NanoDebugger.xaml`),
134+
`NanoCSharpProject`, `NanoDeployableProject`, `LaunchProfiles`.
135+
- **NuGet-generated:** `PkgnanoFramework_Tools_MetadataProcessor_MsBuildTask`.
136+
- **C# task type & parameter names:** `MetaDataProcessorTask`, `ResolveRuntimeDependenciesTask`,
137+
`GenerateBinaryOutputTask`, `GenerateNanoResourceTask`, and params like `Verbose`, `Parse`,
138+
`Compile`, `IsCoreLibrary`, `GenerateSkeletonFile` (fixed by the task classes in
139+
`nanoFramework.Tools.BuildTasks`).
140+
- **Standard MSBuild/.NET-SDK symbols:** `DebugType`, `OutDir`, `TargetName`,
141+
`IntermediateOutputPath`, and the standard hook chains `CoreBuildDependsOn`,
142+
`PrepareForRunDependsOn`, `PrepareResourcesDependsOn`, `ResolveReferencesDependsOn`,
143+
`CleanDependsOn`, etc.
144+
145+
## Back-compat alias pattern (for the C1 + D renamed knobs)
146+
147+
For each renamed user knob, seed the new property from the legacy one before applying its default,
148+
so an existing `.csproj` setting still wins:
149+
150+
```xml
151+
<PropertyGroup>
152+
<!-- Back-compat: honor the legacy NFMDP_PE_Verbose if the project still sets it -->
153+
<NanoMdpVerbose Condition="'$(NanoMdpVerbose)' == '' and '$(NFMDP_PE_Verbose)' != ''">$(NFMDP_PE_Verbose)</NanoMdpVerbose>
154+
<NanoMdpVerbose Condition="'$(NanoMdpVerbose)' == ''">false</NanoMdpVerbose>
155+
</PropertyGroup>
156+
```
157+
158+
Same shape for `NanoMdpVerboseMinimize` ← `NFMDP_PE_VerboseMinimize`, `NanoMdpVersion` ←
159+
`NanoFrameworkMDPVersion`, `DisableNanoMdp` ← `DisableNanoFrameworkMDP`, and `NanoIsCoreLibrary` ←
160+
`IsCoreAssembly`.
161+
162+
## Files touched
163+
164+
All under [src/nanoFramework.NET.Sdk/Sdk/](src/nanoFramework.NET.Sdk/Sdk/):
165+
`Sdk.props`, `Sdk.targets`, `nanoFramework.Tfm.props`, `nanoFramework.Mdp.targets`,
166+
`nanoFramework.Output.targets`, `nanoFramework.Resources.targets`. (`nanoFramework.Capabilities.targets`
167+
needs no change — its symbols are all the fixed CPS contract.) Update the explanatory header
168+
comments that mention the old names (e.g. the `_NfSdkTasksDir` / `NanoFramework_*` / `_NfMdpTasksTFM`
169+
references in the Sdk.targets and Mdp.targets banners).
170+
171+
## Observations surfaced during review (not renames — confirm intent separately)
172+
173+
- In the regular-project `MetaDataProcessor` target, `DumpExports="$(NFMDP_STUB_DumpExports)"` and
174+
`GenerateDependency="$(NFMDP_STUB_GenerateDependency)"` reference properties that are **never
175+
defined**, so they always pass empty. Likely intended to be the `NFMDP_PE_*` equivalents. Flagged
176+
for a follow-up decision; the rename keeps current behavior (empty) unless you confirm a fix.
177+
178+
## Verification
179+
180+
1. Pack/build the SDK: `dotnet build src/nanoFramework.NET.Sdk/nanoFramework.NET.Sdk.csproj`.
181+
2. Build the smoke test against the local SDK:
182+
`dotnet build test/SmokeTest/SmokeTest.csproj -c Debug` — confirm it restores the MDP package,
183+
runs `NanoMetadataProcessor`, and emits `SmokeTest.pe` + `SmokeTest.pdbx` under
184+
`bin/Debug/netnano1.0/` (this exercises the regular-project path + resource gen + binary output +
185+
copy targets).
186+
3. Run a clean: `dotnet build test/SmokeTest/SmokeTest.csproj -t:Clean` — confirm `NanoClean`
187+
removes the `.pe`/`.pdbx`.
188+
4. Set a renamed knob's **legacy** name in a quick test (`-p:NFMDP_PE_Verbose=true`) and confirm the
189+
alias still flows through to verbose MDP output — proving back-compat.
190+
5. Open `test/SmokeTest` in Visual Studio and confirm F5 still routes to the NanoDebugger flavor
191+
(the untouched Capabilities/CPS contract).
192+
193+
The core-assembly (`NanoIsCoreLibrary == true`) path is only exercised by the external mscorlib
194+
repo; review those renames by inspection since this repo has no core-assembly test project.

‎src/nanoFramework.NET.Sdk/Sdk/Rules/NanoDebugger.xaml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!--
3+
Copyright (c) .NET Foundation and Contributors.
4+
Partial Copyright, Microsoft Corporation, All rights reserved.
5+
See LICENSE file in the project root for full license information.
6+
-->
7+
<Rule
8+
Name="NanoDebugger"
9+
DisplayName=".NET nanoFramework Device"
10+
PageTemplate="debugger"
11+
Description=".NET nanoFramework Device debugger options"
12+
xmlns="http://schemas.microsoft.com/build/2009/properties">
13+
<Rule.DataSource>
14+
<DataSource Persistence="UserFileWithXamlDefaults" />
15+
</Rule.DataSource>
16+
17+
<StringProperty Name="NanoDebuggerCommand" DisplayName="Command"
18+
Default="$(TargetPath)"
19+
Description="The debug command to execute.">
20+
<StringProperty.ValueEditors>
21+
<ValueEditor EditorType="DefaultStringPropertyEditor" DisplayName="&lt;Edit...&gt;"/>
22+
<ValueEditor EditorType="DefaultFilePropertyEditor" DisplayName="&lt;Browse...&gt;">
23+
<ValueEditor.Metadata>
24+
<NameValuePair Name="Filters" Value="Executables (*.exe)|*.exe" />
25+
</ValueEditor.Metadata>
26+
</ValueEditor>
27+
</StringProperty.ValueEditors>
28+
</StringProperty>
29+
30+
<StringProperty Name="NanoDebuggerCommandArguments" DisplayName="Command Arguments"
31+
Description="The command line arguments to pass to the application.">
32+
<Argument Property="NanoDebuggerCommand" />
33+
</StringProperty>
34+
<StringProperty Name="NanoDebuggerWorkingDirectory" DisplayName="Working Directory"
35+
Default="$(MSBuildProjectDirectory)"
36+
Description="The application's working directory. By default, the directory containing the project file."
37+
Subtype="folder"/>
38+
<BoolProperty Name="NanoDebuggerDebuggerAttach" DisplayName="Attach"
39+
Default="False"
40+
Description="Specifies whether the debugger should attempt to attach to an existing process when debugging starts." />
41+
</Rule>

0 commit comments

Comments
 (0)