fornever / pascalabc.net.sdk Goto Github PK

View Code? Open in Web Editor NEW

17.0 3.0 2.0 55 KB

MSBuild SDK for PascalABC.NET

License: MIT License

Pascal 4.73% C# 82.52% PowerShell 12.75%

dotnet pascalabcnet

pascalabc.net.sdk's Introduction

PascalABC.NET SDK

This is an MSBuild SDK for PascalABC.NET programming language.

NuGet

FVNever.PascalABC.NET.Compiler:
FVNever.PascalABC.NET.SDK:

Usage

Prerequisites

For now, only Windows is supported as the target platform.
Download .NET 6 SDK or later.

Quick Start

Prepare the following project file, MyProject.pasproj:

<Project Sdk="FVNever.PascalABC.NET.SDK/2.0.1">

   <PropertyGroup>
       <TargetFramework>net472</TargetFramework>
   </PropertyGroup>

   <ItemGroup>
       <MainCompile Include="Hello.pas" />
   </ItemGroup>

</Project>

where Hello.pas is your main Pascal module, for example:

uses References_Generated; // to use SDK-generated assembly references
begin
    writeln('Hello, world!');
end.

After that, dotnet build should build the PascalABC.NET project; see the output in the bin directory.

dotnet run may be used to run the project.

See the PascalABC.NET.SDK.Demo project for details.

Items

In a project, there should be exactly one <MainCompile> item, which will be the main module passed to the compiler.

Other (non-main) .pas files may be added as <Compile> items, which are only used to track incremental compilation dependencies.

References

All the assembly references are resolved during build and written to a generated module References_Generated by default. This means that your main module should add uses References_Generated to access the referenced assemblies.

Properties

You can change the following properties in your project file to customize the SDK behavior.

PascalABCNETCompilerPackageName: the name of the compiler package that will be downloaded from NuGet, FVNever.PascalABC.NET.Compiler by default.
PascalABCNETCompilerPackageVersion: the version of the compiler package to use; may be updated if a new version of the SDK is published.
SkipPascalABCNETCompilerInstallation: set to true to skip the compiler installation by the SDK (if you want to get the compiler yourself via other means).

DebugMode: if true, then the compiler will generate debug information and disable the optimizations. Enabled by default for the Debug configuration.
PascalAbcCompilerCommand: command to run the compiler; just the path to the packaged compiler executable by default.
SkipGenerateReferenceFile: if you don't want the SDK to generate the reference module.

Common MSBuild properties are supported as well.

Development

Before opening the solution or running the unit testing suite, first publish the development packages using this shell command (PowerShell is required):

$ pwsh ./scripts/build-packages.ps1

To execute the tests, run the following shell commands:

$ dotnet test PascalABC.NET.UnitTests
$ dotnet test PascalABC.NET.IntegrationTests

Documentation

pascalabc.net.sdk's People

Contributors

Stargazers

Watchers

Forkers

fredatgithub samuraigh

pascalabc.net.sdk's Issues

Явно обозначить наличие специфичных элементов в `pasproj`

Для элемента MainCompile это можно сделать таким .targets файлом

<Project>
	<ItemGroup>
		<AvailableItemName Include="MainCompile" />
	</ItemGroup>
</Project>

В pasproj нужно будет добавить

<Project>
	...

	<Import Project="path to targets file" />
</Project>

После этого можно например переключать Build Action в Visual Studio

Но я в csproj не наблюдаю таких строчек, по крайней мере в SDK-style проектах. Возможно этот файл можно подключить как-то неявно силами SDK

dotnet test doesn't work with our solution

$ dotnet test
  PascalABC.NET.SDK -> W:\Projects\PascalABC.NET.SDK\PascalABC.NET.SDK\bin\Debug\net6.0\PascalABC.NET.SDK.dll
Starting test execution, please wait...
A total of 1 test files matched the specified pattern.
Testhost process exited with error: Error:
  An assembly specified in the application dependencies manifest (PascalABC.NET.SDK.TestFramework.deps.json) was not found:
    package: 'MedallionShell', version: '1.6.2'
    path: 'lib/netstandard2.0/MedallionShell.dll'
. Please check the diagnostic logs for more information.

Test Run Aborted.

At the same time, if we execute dotnet test separately for every test project (as it is done on CI currently), then it works.

I don't understand the issue, and it should be fixed.

Complex NuGet scenarios

I've found that an old project from this repository couldn't be ported to this SDK, because the references there are mutually dependent.

As of now, I'm investigating if some reference sort could be applied to get them all to load properly by the compiler process.

Project references

We need to add support for <ProjectReference>.

Upload the SDK to the nuget.org

The current usage instructions are very temporary, since the users are expected to download the SDK sources themselves.

We should pack and upload the SDK to the nuget.org, of course.

Upload the compiler to the nuget.org

Currently, the users are expected to install the PascalABC.NET compiler manually.

We should upload it to the nuget.org and use that version by default, both for the end-users and for our own tests.

When closing this, check that there are no TODO[#3] remaining in the source code.

Migrate to the official compiler binaries

After #17, the SDK has migrated to a forked compiler binary. We should migrate back after this PR is merged.

Eliminate all TODO[#18] in the code while resolving this task.

Support platforms other than Windows

Right now, we are trying to run the pabcnetc.exe directly, which will only work on platforms that support this executable (Windows mainly).

We should support Mono on other platforms as well.

(Unfortunately, the story about the compiler which highly depends on System.Reflection.Emit on modern .NET runtimes is very complex, and we'll unlikely be able to run it, say, on .NET 6 soon).

NuGet support

The whole point of this SDK is to allow adding NuGet packages to PascalABC.NET projects.

Ideally, I want everything to be generated automatically: I just add <PackageReference>s to my .pasproj, as usual, and the referenced libraries then automatically get available in the .pas files.

But there are several obstacles among that way; here I'm basing my assumptions on an earlier related investigation.

To add the libraries, we have to add {$reference <relative-dll-path>} to the main module of the application.
- it's impossible to pass referenced assemblies to the compiler via the command line, fine
- is it possible to add these to a non-main module, just generate an empty module full of references and then reference from the main module?
- is it possible to use absolute paths and thus avoid copying of the references?
Since .NET Framework is our main target runtime for now as it seems, we have to generate the App.config for our application. The C# SDK is able to do that automatically; could we reuse the same logic, or should we write our own?
For the compiler to load the referenced assemblies, its own App.config has to be patched as well (the reasons are mentioned in my post linked above). We surely may automate that, but we should choose a strategy. Just copy the whole compiler to obj and then patch in place? Seems fine for now.
We also need to copy the referenced assemblies on build (only for .exe projects actually, but for now we only support such projects anyway).
After we're done with that, please don't forget to share the feedback with compiler authors. It could be useful for them to do some related improvements.

Project template

To simplify the onboarding experience, there should be a project template installable via dotnet new --install.