Repository navigation
AsmFoundation.Sdk 0.2.0
An .asmproj now uses the .NET property of the same purpose wherever one exists, and 0.1.0's
own names are gone, without a compatibility layer. A project
that still sets one fails with an error that names the replacement (ASM0100 to ASM0108),
all of them in one build. Migration:
| 0.1.0 | 0.2.0 |
|---|---|
<AsmLibraryName>hello</AsmLibraryName> |
<AssemblyName>hello</AssemblyName> (still libhello.so, libhello.a, hello) |
<AsmRuntime>Freestanding</AsmRuntime> (the default) |
<TargetFramework>freestanding</TargetFramework> (still the default) |
<AsmRuntime>Libc</AsmRuntime> |
<TargetFramework>libc</TargetFramework> |
<AsmDefineConstants>A;B=1</AsmDefineConstants>, <AsmDefine Include="C" /> |
<DefineConstants>A;B=1;C</DefineConstants> |
<AsmDebugInfo>true</AsmDebugInfo> |
<DebugSymbols>true</DebugSymbols> (<DebugType>none</DebugType> turns it off) |
<AsmEntryPoint>my_entry</AsmEntryPoint> |
<StartupObject>my_entry</StartupObject> |
<AsmLinkFlags>-z defs --version-script=x.map</AsmLinkFlags> |
<LinkerArg Include="-z defs" /> and <ExportsFile>x.map</ExportsFile> |
<AsmOutputKind>StaticLibrary</AsmOutputKind> |
<OutputType>StaticLibrary</OutputType> |
outputs in bin/<Configuration>/ |
outputs in bin/<Configuration>/<TargetFramework>/, as in .NET |
PackageId defaults to AssemblyName, as in .NET, and 0.1.0's AsmLibraryName did not
touch it. Two projects that share an AssemblyName (a static and a shared build of one
library) therefore restore with Ambiguous project name: give each its own PackageId.
Added
- IDE integration, like a
.csproj: Rider, Visual Studio and VS Code show an.asmproj's
files, and opening a solution no longer assembles or links anything.- The asm item types are declared (
AvailableItemName): IDEs show only the item types
they know plus those, so in 0.1.0 Rider showed every.asmprojempty.AsmSourceand
AsmIncludeare also offered as build actions. - Every other file of the project folder is a
Noneitem, as in a.csproj(a linker
script, a C header, a README).EnableDefaultNoneItems=false, .NET's own switch, turns it
off. The managed SDK'sNoneglob could not be reused: with no language source extension,
it removes every file it included. - Design-time builds run no tool. IDEs build a project's design-time view on every
load, callingCompileandCoreCompilewithDesignTimeBuildand
SkipCompilerExecution. 0.1.0 assembled and linked there: slow loads, races with the
real build, and errors such as lld's "cannot open libgrpcasm.a" shown as project
warnings when a referenced project was not built yet.CoreCompilenow honors both
properties, as Csc does. - The fast up-to-date checks of Visual Studio and Rider get
UpToDateCheckInput(the
sources, includes andExportsFile) andUpToDateCheckBuilt(the output), so editing a
.asmfile makes the IDE call MSBuild.
- The asm item types are declared (
- The tooling is .NET only. The end-to-end test is the xunit v3 project
tests/AsmSdk.Tests(dotnet test, 48 tests), and the toolchain is staged by
toolchain/fetch.cs, a .NET 10 file-based app (dotnet run toolchain/fetch.cs -- --rid win-x64). Neither the repository nor CI needs Python.- The tests cover what
tests/run.pychecked, one test per expectation, plus IDE
integration. Through MSBuild they check the declared item types, that every file is
one item, the up-to-date inputs and outputs, and a replay of Rider's design-time build
against a control build that does run the tools. fetch.csdecodes.tar.xzwith SharpCompress (.NET has no xz decoder). On the 901 MB
Windows LLVM archive it took 83.5 s against 78.0 s for Python's lzma, and staged
byte-identical tools.VERSIONS.txtnow ends its lines with LF on every build machine.
- The tests cover what
- Target frameworks:
freestandingandlibc, and<TargetFrameworks>freestanding;libc</TargetFrameworks>
to build both, exactly like a multi-targeted.csproj. Behind the names, freestanding is
netstandard1.0 and libc is netstandard2.0, so NuGet's own rules say who may use what:- a libc project may reference freestanding projects and packages;
- a freestanding project that references a libc-only project fails at restore with
NU1201, and a libc-only package withNU1202; - a project or package that targets both gives each consumer the nearest build. A .NET
project gets the libc build.
- Implicit preprocessor symbols, as in C#:
DEBUGorRELEASE(the configuration),
andFREESTANDINGorLIBC(the target framework), appended after the project body, so
settingDefineConstantsnever drops them.DisableImplicitConfigurationDefinesand
DisableImplicitFrameworkDefinesturn them off. - NativeAOT's names for extra link input:
LinkerArgitems, andExportsFilefor the
version script (with--export-dynamicfor an executable, as NativeAOT does). Editing the
version script relinks. - Package layout per target framework:
build/<framework>/,buildTransitive/<framework>/,
an emptylib/<framework>/_._marker,native/linux-x64/<tfm>/, and, when a project
multi-targets,runtimes/linux-x64/nativeassets/<framework>/for its shared libraries. tests/projects: test projects for the compatibility errors, the removed settings,
StartupObject,ExportsFile,LinkerArg,DefineConstants,DebugSymbols, a
multi-targeted project referencing a single-targeted one, and a libc package consumed by
version.tests/AsmSdk.Testsbuilds them all, and runs the executables.- The
Hello.Librarysample targets both frameworks and reports which build it is
(hello_uses_libc), soHello.Netproves it was given the libc build. - The documentation site, https://asmfoundation.github.io/AsmSdk/: guides, the
complete.asmprojreference, the toolchain and the ecosystem. It is built with DocFX
fromdocs/, with DocFX pinned in.config/dotnet-tools.json, and deployed to GitHub
Pages by.github/workflows/docs.yml.
Changed
-
docs/asmproj.mdis now the complete reference: evaluation order, every item and its
metadata, link lines, the libc stub, and generated files. -
Two corrections in it:
- NASM's messages become MSBuild errors with file and line only with
-Xvc.lld's
messages always do. - A function missing from the libc stub fails executables, not shared libraries.
- NASM's messages become MSBuild errors with file and line only with
-
The package's project URL points at the documentation site, from the next release.
-
Outputs go to
bin/<Configuration>/<TargetFramework>/andobj/<Configuration>/<TargetFramework>/,
as in .NET:bin/Release/libc/hello-libcinstead ofbin/Release/hello-libc. -
Debug information follows
DebugSymbolsandDebugType: DWARF in Debug, none in
Release, as before;DebugSymbols=trueadds it to Release, andDebugType=noneremoves it. -
Every page of the documentation site, the samples and the package readme use the
0.2.0 names.
Removed
tests/run.pyandtoolchain/fetch.py, replaced bytests/AsmSdk.Testsand
toolchain/fetch.cs(see Added).AsmLibraryName,AsmRuntime,AsmDefineConstants,AsmDefineitems,AsmDebugInfo,
AsmEntryPoint,AsmLinkFlagsandAsmOutputKind. See the table above.- The hidden
netstandard2.0target framework of every 0.1.0 project. A project that sets
it now fails withASM0003.
Fixed
- The build targets' comment on
reloc-abs-qwordsaid that a shared object always
resolves adqof a label at load time. That holds only in a writable section:.data,
or.data.rel.rodeclaredwrite. In.rodata, or in any section without the write
flag, the link of a shared library or a Libc executable fails. The comment now says so,
and explains why the warning can stay off: the linker rejects every case that cannot
work. Only the comment changed; the build does the same. - The guide's jump-table rule now covers Libc executables, which are PIEs, as well as
shared libraries. It also says that a Freestanding executable, linked-static, accepts
adqof a label in any section. - Multi-targeting never worked in 0.1.0. The SDK set
TargetFrameworkbefore the
project body, which turned anyTargetFrameworksinto a single-target build, and
Microsoft.NET.Sdk gives the outer build of a project with an unknown extension the
single-target common targets ("Non-CrossTargeting GetTargetFrameworks target should not
be used in cross targeting (outer) build"). The default is now applied after the body,
and the outer build getsMicrosoft.Common.CrossTargeting.targets. - A referenced
.asmprojcould be built with the referencing project's
TargetFramework._AsmResolveProjectReferencesnow removes the same global
properties thatResolveProjectReferencesremoves. - A 0.1.0 package counted as compatible with every framework, because it had no
lib/folder. Thelib/<framework>/_._markers narrow it to the frameworks it was
built for.