From 6164c85d9503ca84662d40321236ae54b700e004 Mon Sep 17 00:00:00 2001 From: Paul Baudron Date: Mon, 26 Jun 2023 17:10:48 +0000 Subject: [PATCH] Update doc to mention Sharpmake Extended layout --- .../Get-Changelog.ps1 | 0 .github/workflows/release.yml | 2 +- CONTRIBUTING.md | 18 ++- README.md | 127 ++++++++++-------- Sharpmake.Platforms/Platforms.md | 45 ------- copy.txt | 13 -- Intro.md => docs/Intro.md | 0 docs/Platforms.md | 27 ++++ 8 files changed, 104 insertions(+), 128 deletions(-) rename Get-Changelog.ps1 => .github/Get-Changelog.ps1 (100%) delete mode 100644 Sharpmake.Platforms/Platforms.md delete mode 100644 copy.txt rename Intro.md => docs/Intro.md (100%) create mode 100644 docs/Platforms.md diff --git a/Get-Changelog.ps1 b/.github/Get-Changelog.ps1 similarity index 100% rename from Get-Changelog.ps1 rename to .github/Get-Changelog.ps1 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index da17c735c..14a91bcce 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -39,7 +39,7 @@ jobs: - name: 'Generating changelog' shell: pwsh - run: .\Get-Changelog.ps1 ${{ github.ref_name }} > changelog.md + run: .github\Get-Changelog.ps1 ${{ github.ref_name }} > changelog.md - name: 'Download workflow artifacts' uses: actions/download-artifact@v3 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb9198b9d..54e73c233 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,19 +1,17 @@ -## Contributing +# Contributing -### Tests +## Tests -We will only accept merge requests that pass every tests. The unit tests are written with NUnit and the regression tests are ran by comparing the samples' output with a reference output. You can run the regression_tests.py script after having built the solution in Visual Studio to run the regression tests. +We will only accept merge requests that pass all tests. The unit tests are written with NUnit and the regression tests are ran by comparing the samples' output with a reference output. You can run the `regression_tests.py` script after having built the solution in Visual Studio to run the regression tests. -Because the regression tests just do a direct comparison with the output, it is possible to get a false negative after having done a good change. In that case, please update the tests so they match the output after your change. You can run the UpdateSamplesOutput.bat and UpdateSharpmakeProjects.bat batch files to automatically overwrite the reference output files. +Because the regression tests just do a direct comparison with the output, it is possible to get a false negative after having done a good change. In that case, please update the tests so they match the output after your change. You can run the `UpdateSamplesOutput.bat` batch files to automatically overwrite the reference output files. Naturally, we also recommend that you put your own tests after fixing a bug or adding a feature to help us avoid regressions. -Functional tests are generating test projects and building them to test functionality +Functional tests are generating test projects and building them to test functionality. -used toolset for functional tests: +## Additional Platforms -tools\FastBuild - v1.01. http://www.fastbuild.org +If you want to add support for an additional platform, please make sure that the platform is open and not tied to any NDA. Ubisoft has not published platform support for most video game consoles for that exact reason. -### Additional Platforms - -If you want to add support for an additional platform, please make sure that the platform is open and that you are not breaking your NDA. Ubisoft has not published platform support for most video game consoles for that exact reason. We will not accept merge requests for new platforms that are not completely open for development. +We will not accept merge requests for new platforms that are not completely open for development. diff --git a/README.md b/README.md index 5587ac991..fedef1ec4 100644 --- a/README.md +++ b/README.md @@ -3,86 +3,95 @@ ![build](https://github.com/ubisoft/Sharpmake/workflows/build/badge.svg) ## Introduction -Sharpmake is a generator for Visual Studio projects and solutions. It is -similar to CMake and Premake, but it is designed for **speed** and -**scale**. Sharpmake has been used at Ubisoft to generate several thousands -of *vcxproj*, *csproj* and *sln* files in a matter of seconds, and each of -these projects can support a large number of Visual Studio configurations as -well. - -That makes Sharpmake ideal for the development of multi-platform games, where -the number of platforms, the different levels of optimization, the multiple -rendering APIs on PC and the level editor can quickly multiply the number of -configurations a given code base must support. Sharpmake generates all those -configurations at once, very quickly. Thus, it becomes trivial to generate -and regenerate the entire project. - -Sharpmake uses C# for scripting, hence the name. That means that you can edit -your scripts in Visual Studio (or Visual Studio Code) and have a complete -IntelliSense programming experience. - -Sharpmake can also generate makefiles and Xcode projects, but it is currently -only available for Windows. With .NET Core and .NET Standard though, it is -our hope that it will eventually cross the platform barrier. In the -meanwhile, you may have luck using it with Mono. - -Sharpmake was developed internally at Ubisoft for Assassin's Creed 3 in 2011. -After experimenting with the other existing tools, it became clear that none -of these solutions were performant enough to generate the number of -configurations needed (at least not in a trivial way) and that a custom -generator was needed. +Sharpmake is a generator for Visual Studio projects and solutions. It is similar to *CMake* and *Premake*, but it is designed for **speed** and **scale**. Sharpmake has been used at Ubisoft to generate several thousands of `.vcxproj`, `.csproj` and `.sln` files in a matter of seconds, and each of these projects can support a large number of Visual Studio configurations as well. + +That makes Sharpmake ideal for the development of multi-platform games, where the number of platforms, the different levels of optimization, the multiple rendering APIs on PC and the level editor can quickly multiply the number of configurations a given code base must support. Sharpmake generates all those configurations at once, very quickly. Thus, it becomes trivial to generate and regenerate the entire project. + +Sharpmake uses the C# language for its scripts, hence the name. That means you can edit your scripts in Visual Studio (or Visual Studio Code) and benefits from the default C# tooling (auto-completion, refactoring, debugger...). + +Sharpmake can also generate makefiles and Xcode projects and can be run "natively" on any modern OSes that support recent version of the dotnet runtime. + +Sharpmake was developed internally at Ubisoft for Assassin's Creed 3 in 2011. After experimenting with the other existing tools, it became clear that none of these solutions were performant enough to generate the number of configurations needed (at least not in a trivial way) and that a custom generator was needed. ## Documentation -The best place for the Sharpmake documentation is the -[wiki on GitHub](https://github.com/ubisoftinc/Sharpmake/wiki). The Sharpmake -source code also comes with samples that you can study. +The Sharpmake documentation is split in two places: +- the [wiki on GitHub](https://github.com/ubisoftinc/Sharpmake/wiki). +- the `doc` folder at the root of the project. + +The Sharpmake source code also comes with samples that you can study. ## Building and running Sharpmake + Building and running Sharpmake is quite straightforward: - Clone the Git repository - Open the `Sharpmake.sln` solution located in the root folder - Hit the run button (by default it will run the first sample) ## More Platforms -Sharpmake originally had support for game consoles, but Ubisoft pulled it out -because those could not be open sourced. Sharpmake now has an extension system -that allows support for these consoles to be added back at runtime. -If you need support for these platforms and are an authorized developer, you -can contact the SDK provider to get platform extension for Sharpmake. +Sharpmake originally had support for game consoles, but Ubisoft pulled it out because those could not be open sourced. Sharpmake now has an extension system that allows support for these consoles to be added back at runtime. + +More information about platforms can be found [here](doc/Platforms.md). + +## Extending Sharpmake + +Sharpmake is an open source project that come with some generic built-in features. + +But as soon as we start speaking about additional features restricted by NDA (like for platforms), or for internal use only, it is handy to have a way to extend it. + +The recommended solution is to follow this folder layout: +``` +SharpmakeExtended: + - 📁 Sharpmake + - 📁 Sharpmake.Platforms + - 📁 Sharpmake.Extensions + - Directory.build.props + - SharpmakeExtended.sln +``` + +1. `📁 Sharpmake` + +The `Sharpmake` folder contains all the files of this Git repository. + +We commonly call it Sharpmake *core*. + +If you plan to version your *SharpmakeExtended* project under Git, you can use a *Git submodule* to pull on it directly. +2. `📁 Sharpmake.Platforms` (and `📁 Sharpmake.Extensions`) -## Contributing +*Platforms vs. Extensions*: there is no difference between them, these two folders are only used to tidy/split things a little. -### Tests -We will only accept merge requests that pass all tests. The unit tests are -written with NUnit and the regression tests are ran by comparing the samples' -output with a reference output. You can run the *regression_tests.py* script -after having built the solution in Visual Studio to run the regression tests. +These two locations are where you can add any additional platforms (or extensions) in there own dedicated folder: +``` +📁 Sharpmake.Platforms + - 📁 Sharpmake.Platform_A + - *.cs + - Sharpmake.Platform_A.csproj + - 📁 Sharpmake.Platform_B + - *.cs + - Sharpmake.Platform_B.csproj +``` -Because the regression tests just do a direct comparison with the output, it is -possible to get a false negative after having done a good change. In that case, -please update the tests so they match the output after your change. You can run -the *UpdateSamplesOutput.bat* and *UpdateSharpmakeProjects.bat* batch files to -automatically overwrite the reference output files. +`Sharpmake.Application.csproj` (from Sharpmake *core*), automatically add `.csproj` from these folders to its dependency list. This means they will automatically be built and copied to its output folder, and simply hitting the "Start Debugging" button will *just work*. -Naturally, we also recommend that you put your own tests after fixing a bug or -adding a feature to help us avoid regressions. +3. `Directory.build.props` -Functional tests are generating test projects and building them to test -functionality +This file is used automatically by your `.csproj` from your platforms and extensions folders. -used toolset for functional tests: +We recommend to - at least - import the same file from the Sharpmake *core* folder to re-use the same basic setup (target framework...). You can also customize/override any option after the import. -tools\FastBuild - v1.04. http://www.fastbuild.org +```xml + + + + + + +``` +4. `SharpmakeExtended.sln` -### Additional Platforms -If you want to add support for an additional platform, please make sure that -the platform is open and that you are not breaking your NDA. Ubisoft has not -published platform support for most video game consoles for that exact reason. -We will not accept merge requests for new platforms that are not completely -open for development. +This solution is only to ease development for humans. It allows to have in a single IDE all the projects from both Sharpmake *core* and the extended ones. diff --git a/Sharpmake.Platforms/Platforms.md b/Sharpmake.Platforms/Platforms.md deleted file mode 100644 index 178123585..000000000 --- a/Sharpmake.Platforms/Platforms.md +++ /dev/null @@ -1,45 +0,0 @@ -# Platforms - -## Open Platforms - -Sharpmake ships with the platform extension *Sharpmake.CommonPlatforms.dll*. -This is a .NET class library that contains everything you need to generate -Visual Studio solutions for C++, C#, and C++/CLI code for Windows. Sharpmake -also has support for generating Xcode and GNU Make-based projects for Mac and -Linux. - -## NDA Platforms - -Sharpmake was originally designed with built-in support for generating -solutions for video game consoles, which are platforms under strict NDA and -private SDKs. In order release Sharpmake to the open-source community, we had -to strip support for those NDA platforms out of the code base and create an -extension mechanism that allows Ubisoft developers to plug these platforms -back in to compile code that depend on it. - -We have pulled the code out simply to comply with our NDA. If you are an -authorized developer outside of Ubisoft and would like to try Sharpmake to -generate projects for Microsoft, Nintendo or Sony platforms, please contact one -of the Sharpmake maintainers on the GitHub repository. - -## Platform References - -Platforms are shipped as ordinary .NET class libraries that are referenced into -Sharpmake script. Because scripts are standalone though, there is no csproj to -add that reference to. Instead, you specify a platform reference with the -`Sharpmake.Reference` module attribute: - -```csharp - [module: Reference(".dll")] -``` - -Sharpmake will look for DLL files in the executable's directory, although a -relative path from the executable should work. - -Please note that *Sharpmake.CommonPlatforms.dll* is always referenced, so -putting `[module: Reference("Sharpmake.CommonPlatforms.dll")]` in your scripts -is redundant. - -There is no problem referencing platforms directly from scripts. The platform -system is designed to isolate Sharpmake itself from the platforms, not the -scripts. diff --git a/copy.txt b/copy.txt deleted file mode 100644 index 33df24b1c..000000000 --- a/copy.txt +++ /dev/null @@ -1,13 +0,0 @@ -// Copyright (c) 2017 Ubisoft Entertainment -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. diff --git a/Intro.md b/docs/Intro.md similarity index 100% rename from Intro.md rename to docs/Intro.md diff --git a/docs/Platforms.md b/docs/Platforms.md new file mode 100644 index 000000000..400538ff9 --- /dev/null +++ b/docs/Platforms.md @@ -0,0 +1,27 @@ +# Platforms + +## Open Platforms + +Sharpmake ships with the platform extension *Sharpmake.CommonPlatforms.dll*. This is a .NET class library that contains everything you need to generate Visual Studio solutions for C++, C#, and C++/CLI code for Windows. Sharpmake also has support for generating Xcode and GNU Make-based projects for Mac and Linux. + +## NDA Platforms + +Sharpmake was originally designed with built-in support for generating projects and solutions for video game consoles, which are platforms under strict NDA and private SDKs. + +In order to release Sharpmake to the open-source community, these platforms have been removed from the code base and an extension mechanism have been created to allow developers to add them back at runtime. + +If you are an *authorized developer* outside of Ubisoft and would like to try Sharpmake to generate projects for Microsoft, Nintendo or Sony platforms, please contact one of the Sharpmake maintainers through the first party developer forums. + +## Referencing platforms from scripts + +Platforms are compiled as ordinary .NET class libraries that are referenced into Sharpmake script. Because scripts are standalone though, there is no `.csproj` to add that reference to. Instead, you specify a platform reference with the `Sharpmake.Reference` module attribute: + +```csharp + [module: Reference(".dll")] +``` + +Sharpmake will look for DLL files in the executable's directory, although a relative path from the executable should work. + +Please note that *Sharpmake.CommonPlatforms.dll* is always referenced, so putting `[module: Reference("Sharpmake.CommonPlatforms.dll")]` in your scripts is redundant. + +There is no problem referencing platforms directly from scripts. The platform system is designed to isolate Sharpmake itself from the platforms, not the scripts.