From a79766514e47698dbf7386cef05e838ca01c536e Mon Sep 17 00:00:00 2001 From: Robbe Beernaert Date: Tue, 2 Dec 2025 11:54:12 +0100 Subject: [PATCH 1/3] fix: updated docs styling for allmodulespublic -> customtoolnamespace (A-C) --- website/docs/allmodulespublic.md | 15 +++++-- website/docs/androidapilevel.md | 10 ++++- website/docs/androidapplibname.md | 10 ++++- website/docs/architecture.md | 59 +++++++++++++++----------- website/docs/assemblydebug.md | 14 ++++-- website/docs/atl.md | 6 +++ website/docs/basedir.md | 10 ++++- website/docs/bindirs.md | 8 +++- website/docs/buildaction.md | 11 ++++- website/docs/buildcommands.md | 8 +++- website/docs/buildcustomizations.md | 10 ++++- website/docs/builddependencies.md | 8 +++- website/docs/buildinputs.md | 8 +++- website/docs/buildlog.md | 10 ++++- website/docs/buildmessage.md | 8 +++- website/docs/buildoptions.md | 13 +++++- website/docs/buildoutputs.md | 8 +++- website/docs/buildstlmodules.md | 17 +++++--- website/docs/callingconvention.md | 20 ++++++--- website/docs/cdialect.md | 43 +++++++++++-------- website/docs/characterset.md | 20 ++++++--- website/docs/clangtidy.md | 15 +++++-- website/docs/cleancommands.md | 8 +++- website/docs/cleanextensions.md | 9 +++- website/docs/clr.md | 26 +++++++----- website/docs/compileas.md | 30 ++++++++----- website/docs/compilebuildoutputs.md | 16 +++++-- website/docs/configfile.md | 8 +++- website/docs/configmap.md | 10 ++++- website/docs/configuration.md | 8 +++- website/docs/configurations.md | 8 +++- website/docs/conformancemode.md | 17 ++++++-- website/docs/consumewinrtextension.md | 15 +++++-- website/docs/copylocal.md | 8 +++- website/docs/cppdialect.md | 61 +++++++++++++++------------ website/docs/csversion.md | 10 ++++- website/docs/customtoolnamespace.md | 7 ++- website/docusaurus.config.js | 5 +++ 38 files changed, 414 insertions(+), 163 deletions(-) diff --git a/website/docs/allmodulespublic.md b/website/docs/allmodulespublic.md index 1ee017bf64..70a6979f8b 100644 --- a/website/docs/allmodulespublic.md +++ b/website/docs/allmodulespublic.md @@ -1,4 +1,10 @@ -allmodulespublic +--- +title: allmodulespublic +description: "Controls whether all C++ modules in the project are exported as public modules." +keywords: [premake,visual studio,modules,public] +--- + +Controls whether all C++ modules in the project are exported as public modules. ```lua allmodulespublic "value" @@ -6,9 +12,10 @@ allmodulespublic "value" ### Parameters ### -`value` one of: -* `On` - All C++ modules in the given project(s) will be public. -* `Off` - Not all C++ modules in the given project(s) will be public. +| value | Description | +| ----- | ------------------------------------------------------------- | +| On | All C++ modules in the given project(s) will be public. | +| Off | Not all C++ modules in the given project(s) will be public.[] | ## Applies To ### diff --git a/website/docs/androidapilevel.md b/website/docs/androidapilevel.md index b16989f5a1..d1310bd52e 100644 --- a/website/docs/androidapilevel.md +++ b/website/docs/androidapilevel.md @@ -1,12 +1,18 @@ +--- +title: androidapilevel +keywords: [premake, android, api, level, config] +description: Specifies the target Android API level. +--- + Specifies the target Android API level. ```lua -androidapilevel (value) +androidapilevel(level) ``` ### Parameters ### -`value` is a number specifying the target Android API level. +`level` **number** - is a number specifying the target Android API level. ## Applies To ### diff --git a/website/docs/androidapplibname.md b/website/docs/androidapplibname.md index fdf90b55d3..43e11d9444 100644 --- a/website/docs/androidapplibname.md +++ b/website/docs/androidapplibname.md @@ -1,14 +1,20 @@ +--- +title: androidapplibname +description: Specfies the file name for the output APK. +keywords: [premake, android, apk, filename, config] +--- + Specfies the file name for the output APK. ```lua -androidapplibname ("value") +androidapplibname ("filename") ``` By default, the project name will be used as the file name for the APK. ### Parameters ### -`value` is the new file name. +`filename` **string** - is the new file name. ## Applies To ### diff --git a/website/docs/architecture.md b/website/docs/architecture.md index fe990c41ff..0713e6f7e5 100644 --- a/website/docs/architecture.md +++ b/website/docs/architecture.md @@ -1,38 +1,47 @@ +--- +title: architecture +description: Specifies the system architecture to be targeted by the configuration. +keywords: [premake, architecture, system, config, x86, x86_64, arm, arm64, riscv64, wasm] +--- + Specifies the system architecture to be targeted by the configuration. ```lua -architecture ("value") +architecture ("arch") ``` ### Parameters ### -`value` is one of: - -* `universal`: The universal binaries supported by iOS and macOS -* `x86` -* `x86_64` -* `ARM` -* `ARM64` -* `RISCV64` -* `loongarch64` -* `ppc` -* `ppc64` -* `wasm32`, -* `wasm64`, -* `e2k`, -* `mips64el`, -* `armv5`: Only supported in VSAndroid projects -* `armv7`: Only supported in VSAndroid projects -* `aarch64`: Only supported in VSAndroid projects -* `mips`: Only supported in VSAndroid projects -* `mips64`: Only supported in VSAndroid projects +| Arch | Description | +|-------------|--------------------------------------------------| +| universal | Universal binaries supported by iOS and macOS | +| x86 | 32-bit x86 architecture | +| x86_64 | 64-bit x86 architecture | +| ARM | 32-bit ARM architecture | +| ARM64 | 64-bit ARM architecture | +| RISCV64 | 64-bit RISC-V architecture | +| loongarch64 | 64-bit LoongArch architecture | +| ppc | 32-bit PowerPC architecture | +| ppc64 | 64-bit PowerPC architecture | +| wasm32 | 32-bit WebAssembly target | +| wasm64 | 64-bit WebAssembly target | +| e2k | Elbrus 2000 architecture | +| mips64el | 64-bit MIPS little-endian architecture | +| armv5 | ARMv5 (only supported in VSAndroid projects) | +| armv7 | ARMv7 (only supported in VSAndroid projects) | +| aarch64 | AArch64 (only supported in VSAndroid projects) | +| mips | MIPS (only supported in VSAndroid projects) | +| mips64 | 64-bit MIPS (only supported in VSAndroid projects) | Additional values that are aliases for the above: -* `i386`: Alias for `x86` -* `amd64`: Alias for `x86_64` -* `x32`: Alias for `x86`; There is intent to deprecate this -* `x64`: Alias for `x86_64`; There is intent to deprecate this +| arch | Description | +|-------|-----------------------------------------------| +| i386 | Alias for `x86` | +| amd64 | Alias for `x86_64` | +| x32 | Alias for `x86`; there is intent to deprecate | +| x64 | Alias for `x86_64`; there is intent to deprecate | + ### Applies To ### diff --git a/website/docs/assemblydebug.md b/website/docs/assemblydebug.md index 7c996b5752..fc850be222 100644 --- a/website/docs/assemblydebug.md +++ b/website/docs/assemblydebug.md @@ -1,12 +1,18 @@ -assemblydebug - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request. +--- +title: assemblydebug +description: Generates assembly-level debug information in Visual Studio projects +keywords: [premake, assemblydebug, visual studio, debug, config] +--- + +Generates assembly-level debug information in Visual Studio projects ```lua -assemblydebug (value) +assemblydebug(enable) ``` ### Parameters ### -`value` - needs documentation. +`enable` **boolean** - enable/disable assemblydebug. ## Applies To ### @@ -19,6 +25,6 @@ Premake 5.0.0 alpha 16 or later. ### Examples ### ```lua -assemblydebug (value) +assemblydebug(true) ``` diff --git a/website/docs/atl.md b/website/docs/atl.md index 989d1cb941..1be9e3d012 100644 --- a/website/docs/atl.md +++ b/website/docs/atl.md @@ -1,3 +1,9 @@ +--- +title: atl +description: Enables Microsoft's Active Template Library in a project. +keywords: [premake, atl, active template library, visual studio, project, config] +--- + Enables Microsoft's Active Template Library in a project. ```lua diff --git a/website/docs/basedir.md b/website/docs/basedir.md index f0b8da1d79..e24fad48b8 100644 --- a/website/docs/basedir.md +++ b/website/docs/basedir.md @@ -1,14 +1,20 @@ +--- +title: basedir +description: Sets the base directory for a configuration +keywords: [premake, basedir, base directory, path, configuration] +--- + Sets the base directory for a configuration, from with other paths contained by the configuration will be made relative at export time. ```lua -basedir ("value") +basedir ("path") ``` You do not normally need to set this value, as it is filled in automatically with the current working directory at the time the configuration block is created by the script. ### Parameters ### -`value` is an absolute path, from which other paths contained by the configuration should be made relative. +`path` **string** - is an absolute path, from which other paths contained by the configuration should be made relative. ### Applies To ### diff --git a/website/docs/bindirs.md b/website/docs/bindirs.md index d22758d67b..f78bad4a8b 100644 --- a/website/docs/bindirs.md +++ b/website/docs/bindirs.md @@ -1,3 +1,9 @@ +--- +title: bindirs +description: Specifies extra paths to use when executing build commands +keywords: [premake, bindirs, build commands, executable paths, config] +--- + Specifies extra paths to use when executing build commands ```lua @@ -6,7 +12,7 @@ bindirs { "directories" } ### Parameters ### -`directories` - paths containing executable to run when building command. +`directories` **string[]** - paths containing executable to run when building command. ### Applies To ### diff --git a/website/docs/buildaction.md b/website/docs/buildaction.md index e5a9c4094b..9ba393b856 100644 --- a/website/docs/buildaction.md +++ b/website/docs/buildaction.md @@ -1,3 +1,9 @@ +--- +title: buildaction +description: Specifies how a file or set of files should be treated during the compilation process +keywords: [premake, buildaction, msbuild, visual studio, compile, embed, copy, resource, config] +--- + Specifies how a file or set of files should be treated during the compilation process. It is usually paired with a filter to select a file set. If no build action is specified for a file a default action will be used, based on the file's extension. ```lua @@ -23,8 +29,10 @@ For C/C++, `action` is the name of the MSBuild action as defined by the vcxproj | AppxManifest | Treat the file as AppX Manifest; required for UWP applications. | | Copy | Copy the file to the target directory. | +:::warning For C# projects, `buildaction` behaviour is special to support legacy implementation. In C#, `action` is one of +::: | Action | Description | |-------------|-----------------------------------------------------------------------| @@ -38,8 +46,9 @@ In C#, `action` is one of | Resource | Copy/embed the file with the project resources. | | UserControl | Treat the source file as [visual user control][2]. | +:::warning The descriptive actions such as **Component**, **Form*, and **UserControl** are only recognized by Visual Studio, and may be considered optional as Visual Studio will automatically deduce the types when it first examines the project. You only need to specify these actions to avoid unnecessary modifications to the project files on save. - +::: ### Applies To ### File configurations. diff --git a/website/docs/buildcommands.md b/website/docs/buildcommands.md index 0ad27aa2f2..965fcfc5e6 100644 --- a/website/docs/buildcommands.md +++ b/website/docs/buildcommands.md @@ -1,3 +1,9 @@ +--- +title: buildcommands +description: Specifies one or more shell commands to be executed to build a project or file +keywords: [premake, buildcommands, shell, makefile, custom, config] +--- + Specifies one or more shell commands to be executed to build a project or file. ```lua @@ -6,7 +12,7 @@ buildcommands { "commands" } ### Parameters ### -`commands` specifies a list of one or more shell commands to be executed. The commands may use [tokens](Tokens.md). +`commands` **string[]** - specifies a list of one or more shell commands to be executed. The commands may use [tokens](Tokens.md). ### Applies To ### diff --git a/website/docs/buildcustomizations.md b/website/docs/buildcustomizations.md index cb93dbbc46..41d0d1bb97 100644 --- a/website/docs/buildcustomizations.md +++ b/website/docs/buildcustomizations.md @@ -1,12 +1,18 @@ +--- +title: buildcustomizations +description: Imports custom .props files for Visual Studio. +keywords: [premake, buildcustomizations, visual studio, props, project] +--- + Imports custom .props files for Visual Studio. ```lua -buildcustomizations { "string" } +buildcustomizations { "name" } ``` ### Parameters ### -`value` - needs documentation. +`name` **string** — The name of the Visual Studio build customization to import (corresponding to a `.props` file, without extension).. ### Applies To ### diff --git a/website/docs/builddependencies.md b/website/docs/builddependencies.md index 9b1e340977..6c59c7aabb 100644 --- a/website/docs/builddependencies.md +++ b/website/docs/builddependencies.md @@ -1,3 +1,9 @@ +--- +title: builddependencies +description: Specifies any additional dependencies for the target of a custom build rule. +keywords: [premake, builddependencies, dependencies] +--- + Specifies any additional dependencies for the target of a custom build rule. ```lua @@ -6,7 +12,7 @@ builddependencies { "files" } ### Parameters ### -`files` specifies a list of file path for additional dependencies. +`files` **string[]** - specifies a list of file paths for additional dependencies. ### Applies To ### diff --git a/website/docs/buildinputs.md b/website/docs/buildinputs.md index f3c5d7d749..801db71b49 100644 --- a/website/docs/buildinputs.md +++ b/website/docs/buildinputs.md @@ -1,3 +1,9 @@ +--- +title: buildinputs +description: Specifies the source file file inputs of a custom build command or rule. +keywords: [premake, buildinputs, custom build, inputs, source files, project config] +--- + Specifies the source file file inputs of a custom build command or rule. ```lua @@ -6,7 +12,7 @@ buildinputs { "inputs" } ### Parameters ### -`inputs` is the list of input source files. +`inputs` **string** - is the list of input source files. ### Applies To ### diff --git a/website/docs/buildlog.md b/website/docs/buildlog.md index d42683b532..2dccc0e71f 100644 --- a/website/docs/buildlog.md +++ b/website/docs/buildlog.md @@ -1,14 +1,20 @@ +--- +title: buildlog +description: Specifies the output location of a toolset's build logs. +keywords: [premake, buildlog, build logs, visual studio, project config, path] +--- + Specifies the output location of a toolset's build logs. ```lua -buildlog ("path") +buildlog("path") ``` If a build log path has not been specified, the toolset's default path will be used. ### Parameters ### -`path` is the output file system location for the build log file. +`path` **string** - is the output file system location for the build log file. ### Applies To ### diff --git a/website/docs/buildmessage.md b/website/docs/buildmessage.md index bf786ecadc..3cb7cf0003 100644 --- a/website/docs/buildmessage.md +++ b/website/docs/buildmessage.md @@ -1,3 +1,9 @@ +--- +title: buildmessage +description: Specifies the text to output to the when a custom build command or rule is executed. +keywords: [premake, buildmessage, custom build, message, output, project config, rules] +--- + Specifies the text to output to the when a custom build command or rule is executed. ```lua @@ -6,7 +12,7 @@ buildmessage ("message") ### Parameters ### -`message` is the text to write to standard output. +`message` **string** - is the text to write to standard output. ### Applies To ### diff --git a/website/docs/buildoptions.md b/website/docs/buildoptions.md index d35de0ac9d..714777cb02 100644 --- a/website/docs/buildoptions.md +++ b/website/docs/buildoptions.md @@ -1,14 +1,21 @@ +--- +title: buildoptions +description: Passes arguments directly to the compiler command line without translation. +keywords: [premake, buildoptions, compiler flags, command line, gmake, project config] +--- + Passes arguments directly to the compiler command line without translation. ```lua buildoptions { "options" } ``` - +:::warning If a project includes multiple calls to `buildoptions` the lists are concatenated, in the order in which they appear in the script. +::: ### Parameters ### -`options` is a list of compiler flags and options, specific to a particular compiler. +`options` **string[]** - is a list of compiler flags and options, specific to a particular compiler. ### Applies To ### @@ -20,7 +27,9 @@ Premake 4.0 or later. ### Examples ### +:::warning Use `pkg-config` style configuration when building on Linux with GCC. Build options are always compiler specific and should be targeted to a particular toolset. +::: ```lua filter { "system:linux", "action:gmake" } diff --git a/website/docs/buildoutputs.md b/website/docs/buildoutputs.md index 05d208965a..2d2ea6a5bf 100644 --- a/website/docs/buildoutputs.md +++ b/website/docs/buildoutputs.md @@ -1,3 +1,9 @@ +--- +title: buildoutputs +description: Specifies the file outputs of a custom build command or rule. +keywords: [premake, buildoutputs, custom build, outputs, files, project config, rules] +--- + Specifies the file outputs of a custom build command or rule. ```lua @@ -6,7 +12,7 @@ buildoutputs { "output" } ### Parameters ### -`output` is the file that is created or updated by the custom build command or rule. +`output` **string[]** - is the file that is created or updated by the custom build command or rule. ### Applies To ### diff --git a/website/docs/buildstlmodules.md b/website/docs/buildstlmodules.md index 1836a8c237..fe917068b1 100644 --- a/website/docs/buildstlmodules.md +++ b/website/docs/buildstlmodules.md @@ -1,15 +1,22 @@ +--- +title: buildstlmodules +description: Sets whether or not the compiler should build STL modules. +keywords: [premake, buildstlmodules, stl modules, visual studio, compiler, config] +--- + Sets whether or not the compiler should build STL modules. ```lua -buildstlmodules("value") +buildstlmodules("enabled") ``` ### Parameters ### -`value` is one of: +| Enabled | Description | +| ------- | ------------------- | +| On | Enable stl modules | +| Off | Disable stl modules | -- `On` -- `Off` ### Applies To ### @@ -21,4 +28,4 @@ Premake 5.0.0 beta 3 or later for Visual Studio 2022 and later. ### See Also ### -* [enablemodules](enablemodules.md) \ No newline at end of file +* [enablemodules](enablemodules.md) diff --git a/website/docs/callingconvention.md b/website/docs/callingconvention.md index 5fd90537de..ed19d07877 100644 --- a/website/docs/callingconvention.md +++ b/website/docs/callingconvention.md @@ -1,17 +1,25 @@ +--- +title: callingconvention +description: Sets whether or not the compiler should build STL modules. +keywords: [premake, callingconvention, cdecl, fastcall, stdcall, vectorcall, function calling convention, compiler, project config] +--- + + Sets the [function calling convention](https://en.wikipedia.org/wiki/X86_calling_conventions). ```lua -callingconvention ("value") +callingconvention ("convention") ``` ### Parameters ### -`value` is one of: +| Convention | Description | +|-------------|-----------------------------------------------------------------------------| +| Cdecl | Standard C calling convention; caller cleans the stack after the function. | +| FastCall | Passes some arguments via registers for faster function calls. | +| StdCall | Standard calling convention for WinAPI; callee cleans the stack. | +| VectorCall | Optimized for vector types; passes arguments in registers for performance. | -* `Cdecl` -* `FastCall` -* `StdCall` -* `VectorCall` ### Applies To ### diff --git a/website/docs/cdialect.md b/website/docs/cdialect.md index bd3024fe90..eb308572e6 100644 --- a/website/docs/cdialect.md +++ b/website/docs/cdialect.md @@ -1,26 +1,33 @@ -cdialect +--- +title: cdialect +description: Sets the C language dialect for the compiler. +keywords: [premake, cdialect, c dialect, c89, c99, c11, c17, c23, gnu dialects, compiler, project config] +--- + +Sets the C language dialect for the compiler. ```lua -cdialect "value" +cdialect "dialect" ``` ### Parameters ### -`value` one of: - -* `Default`: the default C dialect for the toolset -* `C89`: ISO C89 -* `C90`: ISO C90 -* `C99`: ISO C99 -* `C11`: ISO C11 -* `C17`: ISO C17 -* `C23`: ISO C23 -* `gnu89`: GNU dialect of ISO C89 -* `gnu90`: GNU dialect of ISO C90 -* `gnu99`: GNU dialect of ISO C99 -* `gnu11`: GNU dialect of ISO C11 -* `gnu17`: GNU dialect of ISO C17 -* `gnu23`: GNU dialect of ISO C23 +| Dialect | Description | +| ------- | ------------------------------------- | +| Default | The default C dialect for the toolset | +| C89 | ISO C89 standard | +| C90 | ISO C90 standard | +| C99 | ISO C99 standard | +| C11 | ISO C11 standard | +| C17 | ISO C17 standard | +| C23 | ISO C23 standard | +| gnu89 | GNU dialect of ISO C89 | +| gnu90 | GNU dialect of ISO C90 | +| gnu99 | GNU dialect of ISO C99 | +| gnu11 | GNU dialect of ISO C11 | +| gnu17 | GNU dialect of ISO C17 | +| gnu23 | GNU dialect of ISO C23 | + ### Applies To ### @@ -33,6 +40,6 @@ Premake 5.0.0 alpha 12 or later. ### Examples ### ```lua -cdialect "value" +cdialect "dialect" ``` diff --git a/website/docs/characterset.md b/website/docs/characterset.md index 1c3567f220..ba81eb03dd 100644 --- a/website/docs/characterset.md +++ b/website/docs/characterset.md @@ -1,17 +1,23 @@ +--- +title: characterset +description: Set the character encoding. +keywords: [premake, characterset, character encoding, unicode, mbcs, ascii, compiler, project config] +--- + Set the character encoding. ```lua -characterset ("value") +characterset("set") ``` ### Parameters ### -`value` is one of: - -* `Default`: the default encoding for the toolset; usually `Unicode` -* `MBCS`: Multi-byte Character Set; currently Visual Studio only -* `Unicode`: Unicode character encoding -* `ASCII`: No actual character set +| Set | Description | +| ------- | ------------------------------------------------------------------- | +| Default | The default encoding for the toolset; usually Unicode | +| MBCS | Multi-byte Character Set; currently supported only in Visual Studio | +| Unicode | Unicode character encoding | +| ASCII | No actual character set; plain 7-bit ASCII encoding | ### Applies To ### diff --git a/website/docs/clangtidy.md b/website/docs/clangtidy.md index 6af12a4425..1d84f859b2 100644 --- a/website/docs/clangtidy.md +++ b/website/docs/clangtidy.md @@ -1,17 +1,24 @@ +--- +title: clangtidy +description: Enables clang-tidy code analysis for Visual Studio. +keywords: [premake, clangtidy, clang tidy, code analysis, static analysis, visual studio] +--- + Enables clang-tidy code analysis for Visual Studio. The `clangtidy` option enables running clang-tidy code analysis in Visual Studio projects. ```lua -clangtidy("value") +clangtidy("enabled") ``` ### Parameters ### -`value` is one of: +| Enabled | Description | +| ------- | ------------------ | +| On | Enable clang tidy | +| Off | Disable clang tidy | -- `On` -- `Off` ### Applies To ### diff --git a/website/docs/cleancommands.md b/website/docs/cleancommands.md index 597ad895a7..1baed99536 100644 --- a/website/docs/cleancommands.md +++ b/website/docs/cleancommands.md @@ -1,3 +1,9 @@ +--- +title: cleancommands +description: Specifies one or more shell commands to be executed to clean a Makefile project +keywords: [premake, cleancommands, makefile, shell, project cleanup] +--- + Specifies one or more shell commands to be executed to clean a [Makefile project](Makefile-Projects.md). ```lua @@ -6,7 +12,7 @@ cleancommands { "commands" } ### Parameters ### -`commands` specifies a list of one or more shell commands to be executed. The commands may use tokens. +`commands` **string[]** - specifies a list of one or more shell commands to be executed. The commands may use tokens. ### Applies To ### diff --git a/website/docs/cleanextensions.md b/website/docs/cleanextensions.md index 91f938f6c0..eab18945f3 100644 --- a/website/docs/cleanextensions.md +++ b/website/docs/cleanextensions.md @@ -1,3 +1,10 @@ +--- +title: cleanextensions +description: Specifies one or more file extensions to find and remove when cleaning the project. +keywords: [premake, cleancommands, makefile, shell, project cleanup] +--- + + Specifies one or more file extensions to find and remove when cleaning the project. ```lua @@ -6,7 +13,7 @@ cleanextensions { ".ext1", ".ext2" } ### Parameters ### -A list of dot-prefixed file extensions to be cleaned. +`extension` **string[]** - A list of dot-prefixed file extensions to be cleaned. ### Applies To ### diff --git a/website/docs/clr.md b/website/docs/clr.md index 2be691ab2d..fc9a364706 100644 --- a/website/docs/clr.md +++ b/website/docs/clr.md @@ -1,23 +1,27 @@ +--- +title: clr +description: Enables Microsoft's Common Language Runtime for a project or configuration. +keywords: [premake, clr, common language runtime, managed c++, netcore, .NET Core, visual studio] +--- + Enables Microsoft's Common Language Runtime for a project or configuration. ```lua -clr "value" +clr "type" ``` See [/clr (Common Language Runtime Compilation)](http://msdn.microsoft.com/en-us/library/k8d11d4s.aspx) in the Visual Studio documentation for more information. ### Parameters ### -`value` is one of the following: - -| Value | Description | -|-------------|------------------------------------------------------------------------| -| Off | No CLR support | -| On | Enable CLR support | -| Pure | Enable pure mode MSIL. Equivalent to "On" for .NET projects. | -| Safe | Enable verifiable MSIL. Equivalent to "On" for .NET projects. | -| Unsafe | Enable unsafe operations. Equivalent to "On" for Managed C++ projects. | -| NetCore | Needs documentation | +| Type | Description | +| ------- | ------------------------------------------------------------------------------------- | +| Off | No CLR support | +| On | Enable CLR support | +| Pure | Enable pure mode MSIL. Equivalent to "On" for .NET projects. | +| Safe | Enable verifiable MSIL. Equivalent to "On" for .NET projects. | +| Unsafe | Enable unsafe operations. Equivalent to "On" for Managed C++ projects. | +| NetCore | Targets .NET Core/.NET 5+ with C++/CLI projects. Builds managed DLLs for modern .NET. | CLR settings that do not make sense for the current configuration, such setting CLR support for a C# project to "Off", will be ignored. diff --git a/website/docs/compileas.md b/website/docs/compileas.md index 30e68113a3..be80d0641f 100644 --- a/website/docs/compileas.md +++ b/website/docs/compileas.md @@ -1,20 +1,28 @@ -compileas +--- +title: compileas +description: Specify how a source file should be compiled, regardless of its extension. +keywords: [premake, compileas, compile type] +--- + +Specify how a source file should be compiled, regardless of its extension. ```lua -compileas "value" +compileas "type" ``` ### Parameters ### -`value` one of: -* `Default` - Compile based on file extensions that have been built into premake. -* `C` - Compile as a C source file. -* `C++` - Compile as a C++ source file. -* `Objective-C` - Compile as an Objective-C source file. -* `Objective-C++` - Compile as an Objective-C++ source file. -* `Module` - Compile as a C++20 module interface unit. -* `ModulePartition` - Compile as a C++20 module interface partition. -* `HeaderUnit` - Compile as a C++20 header unit. +| Type | Description | +| --------------- | ------------------------------------------------------------------- | +| Default | Compile based on file extensions that have been built into Premake. | +| C | Compile as a C source file. | +| C++ | Compile as a C++ source file. | +| Objective-C | Compile as an Objective-C source file. | +| Objective-C++ | Compile as an Objective-C++ source file. | +| Module | Compile as a C++20 module interface unit. | +| ModulePartition | Compile as a C++20 module interface partition. | +| HeaderUnit | Compile as a C++20 header unit. | + ### Applies To ### diff --git a/website/docs/compilebuildoutputs.md b/website/docs/compilebuildoutputs.md index f9342f1a53..a29cc72df9 100644 --- a/website/docs/compilebuildoutputs.md +++ b/website/docs/compilebuildoutputs.md @@ -1,14 +1,22 @@ +--- +title: compilebuildoutputs +description: Specify if generated file from buildcommands should be compiled or not. +keywords: [premake, compilebuildoutputs, buildcommands, buildoutputs, custom build, generated files, project config] +--- + Specify if generated file from [`buildcommands`](buildcommands.md) should be compiled or not. ```lua -compilebuildoutputs "value" +compilebuildoutputs "enabled" ``` ### Parameters ### -`value` one of: -* `on` - generated file should be compiled. -* `off` - generated file should not be compiled. +| Enabled | Description | +| ------- | -------------------------------------- | +| on | Generated file should be compiled. | +| off | Generated file should not be compiled. | + ### Applies To ### diff --git a/website/docs/configfile.md b/website/docs/configfile.md index 8472dcea8f..a1c376bfba 100644 --- a/website/docs/configfile.md +++ b/website/docs/configfile.md @@ -1,3 +1,9 @@ +--- +title: configfile +description: Specifies an Xbox 360 configuration file. +keywords: [premake, configfile, xbox 360, configuration file, project config] +--- + Specifies an Xbox 360 configuration file. ```lua @@ -6,7 +12,7 @@ configfile "file" ### Parameters ### -`file` is the script-relative path to the configuration file. +`file` **string** - is the script-relative path to the configuration file. ### Applies To ### diff --git a/website/docs/configmap.md b/website/docs/configmap.md index e5e2ddca0e..474f4e4037 100644 --- a/website/docs/configmap.md +++ b/website/docs/configmap.md @@ -1,3 +1,9 @@ +--- +title: configmap +description: Map workspace level configuration and platforms to a different project configuration or platform. +keywords: [premake, configmap, configuration mapping, platforms] +--- + Map workspace level configuration and platforms to a different project configuration or platform. ```lua @@ -9,9 +15,9 @@ You may map multiple configurations in a single configuration map. ### Parameters ### -`wks_cfg` is the workspace configuration being mapped. It can be a string representing a build configuration or a platform, or a table holding a build configuration/platform pair. +`wks_cfg` **string | table** - is the workspace configuration being mapped. It can be a string representing a build configuration or a platform, or a table holding a build configuration/platform pair. -`prj_cfg` is the project configuration to which the workspace configuration should be mapped. It may also be a string or a build configuration/platform pair. +`prj_cfg` **string | table** - is the project configuration to which the workspace configuration should be mapped. It may also be a string or a build configuration/platform pair. ### Applies To ### diff --git a/website/docs/configuration.md b/website/docs/configuration.md index 9519ad85b2..56f8b69e06 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -1,3 +1,9 @@ +--- +title: configuration +description: Limits the subsequent build settings to a particular environment. +keywords: [premake, configuration, deprecated] +--- + :::caution **This function has been deprecated in Premake 5.0 beta1.** Use the new [filter()](filter.md) function instead; you will get more granular matching and much better performance. `configuration()` will be not supported in Premake 6. ::: @@ -10,7 +16,7 @@ configuration { "keywords" } ### Parameters ### -`keywords` is a list of identifiers (see below). When all of the keywords in this list match Premake's current context, the settings that follow the `configuration` statement will be applied. If any of the identifiers are not in the current context the settings will be ignored. +`keywords` **string[]** - is a list of identifiers (see below). When all of the keywords in this list match Premake's current context, the settings that follow the `configuration` statement will be applied. If any of the identifiers are not in the current context the settings will be ignored. The available sources for keywords. Keywords are not case-sensitive. diff --git a/website/docs/configurations.md b/website/docs/configurations.md index 9be24e90b0..e4a3f0c3dd 100644 --- a/website/docs/configurations.md +++ b/website/docs/configurations.md @@ -1,3 +1,9 @@ +--- +title: configurations +description: Specifies the set of build configurations. +keywords: [premake, configurations, debug, release] +--- + Specifies the set of build configurations, such as "Debug" and "Release", for a workspace or project. ```lua @@ -10,7 +16,7 @@ For more information, see [Configurations and Platforms](Configurations-and-Plat ### Parameters ### -`names` is a list of configuration names. Spaces are allowed, but may make using certain Premake features, such as a command-line configuration selection, more difficult. +`names` **string[]** - is a list of configuration names. Spaces are allowed, but may make using certain Premake features, such as a command-line configuration selection, more difficult. ### Applies To ### diff --git a/website/docs/conformancemode.md b/website/docs/conformancemode.md index db4f0673b4..5515d55a6e 100644 --- a/website/docs/conformancemode.md +++ b/website/docs/conformancemode.md @@ -1,12 +1,23 @@ -conformancemode - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request. +--- +title: conformancemode +description: Enables or disables the compiler’s standards conformance mode. +keywords: [premake, conformancemode, standards conformance, permissive-, c++, visual studio, compiler options] +--- + +Controls whether the compiler enforces strict language standards conformance. +In Visual Studio, this corresponds to the `/permissive-` option, which turns on standard‑compliant C++ behavior and disables certain non‑standard Microsoft extensions. ```lua -conformancemode (value) +conformancemode(enabled) ``` ### Parameters ### -`value` - needs documentation. +| enabled | Description | +| ------- | -------------------------------------------------------------------------------------------- | +| On | Enable standards‑conformance mode (`/permissive-`), enforcing strict C++ compliance. | +| Off | Disable standards‑conformance mode, allowing Microsoft extensions and non‑standard behavior. | + ## Applies To ### diff --git a/website/docs/consumewinrtextension.md b/website/docs/consumewinrtextension.md index 781d86c6be..edf8b0a886 100644 --- a/website/docs/consumewinrtextension.md +++ b/website/docs/consumewinrtextension.md @@ -1,3 +1,9 @@ +--- +title: consumewinrtextension +description: Enables the WinRT extension. +keywords: [premake, consumewinrtextension, winrt, c++/cx, visual studio, compiler options] +--- + Enables the WinRT extension, C++/CX, for the specified projects/files. ```lua @@ -6,10 +12,11 @@ consumewinrtextension "value" ### Parameters ### -`value` is one of: -* `Default` - Compiles the file using the default for the toolset. (Default is `Off`) -* `On` - Compiles the file with the WinRT extension enabled. -* `Off` - Compiles the file without the WinRT extension enabled. +| Value | Description | +|---------|-----------------------------------------------------------------------------| +| Default | Compiles the file using the default for the toolset. (Default is `Off`) | +| On | Compiles the file with the WinRT extension enabled. | +| Off | Compiles the file without the WinRT extension enabled. | ### Applies To ### diff --git a/website/docs/copylocal.md b/website/docs/copylocal.md index 4c7074d030..f0cba14d0a 100644 --- a/website/docs/copylocal.md +++ b/website/docs/copylocal.md @@ -1,3 +1,9 @@ +--- +title: copylocal +description: Specifies a list of libraries or assembly references which should be copied to the target directory as part of the build. +keywords: [premake, copylocal, assemblies, libraries, c#, visual studio] +--- + Specifies a list of libraries or assembly references which should be copied to the target directory as part of the build. Refer to the Visual Studio C# project feature of the same name. ```lua @@ -10,7 +16,7 @@ Note that, by default, all referenced non-system assemblies in a C# project are ### Parameters ### -`libraries` is a list of the libraries or assemblies to be copied as part of the build. The names specified here should match the names used in the call to `links()`. +`libraries` **string[]** - is a list of the libraries or assemblies to be copied as part of the build. The names specified here should match the names used in the call to `links()`. ### Applies To ### diff --git a/website/docs/cppdialect.md b/website/docs/cppdialect.md index 792893c918..585ed6bffc 100644 --- a/website/docs/cppdialect.md +++ b/website/docs/cppdialect.md @@ -1,4 +1,10 @@ -cppdialect +--- +title: cppdialect +description: Sets the C++ language standard or dialect for compilation. +keywords: [premake, cppdialect, c++ standard, c++ dialect, compiler options] +--- + +Select which C++ standard (ISO or GNU) the compiler should use, e.g. `C++17` or `gnu++20`. ```lua cppdialect "value" @@ -6,32 +12,33 @@ cppdialect "value" ### Parameters ### -`value` one of: - -* `Default`: the default C++ dialect for the toolset -* `C++latest`: the latest C++ dialect for the toolset or action where available, otherwise the latest C++ dialect supported by Premake -* `C++98`: ISO C++98 -* `C++0x`: ISO C++11 Draft -* `C++11`: ISO C++11 -* `C++1y`: ISO C++14 Draft -* `C++14`: ISO C++14 -* `C++1z`: ISO C++17 Draft -* `C++17`: ISO C++17 -* `C++2a`: ISO C++20 Draft -* `C++20`: ISO C++20 -* `C++2b`: ISO C++23 Draft -* `C++23`: ISO C++23 -* `gnu++98`: GNU dialect of ISO C++98 -* `gnu++0x`: GNU dialect of ISO C++11 Draft -* `gnu++11`: GNU dialect of ISO C++11 -* `gnu++1y`: GNU dialect of ISO C++14 Draft -* `gnu++14`: GNU dialect of ISO C++14 -* `gnu++1z`: GNU dialect of ISO C++17 Draft -* `gnu++17`: GNU dialect of ISO C++17 -* `gnu++2a`: GNU dialect of ISO C++20 Draft -* `gnu++20`: GNU dialect of ISO C++20 -* `gnu++2b`: GNU dialect of ISO C++23 Draft -* `gnu++23`: GNU dialect of ISO C++23 +| Value | Description | +| --------- | ----------------------------------------------------------------------------------------- | +| Default | The default C++ dialect for the toolset (default is `Off`). | +| C++latest | Latest C++ dialect for the toolset/action if available, else latest supported by Premake. | +| C++98 | ISO C++98 | +| C++0x | ISO C++11 Draft | +| C++11 | ISO C++11 | +| C++1y | ISO C++14 Draft | +| C++14 | ISO C++14 | +| C++1z | ISO C++17 Draft | +| C++17 | ISO C++17 | +| C++2a | ISO C++20 Draft | +| C++20 | ISO C++20 | +| C++2b | ISO C++23 Draft | +| C++23 | ISO C++23 | +| gnu++98 | GNU dialect of ISO C++98 | +| gnu++0x | GNU dialect of ISO C++11 Draft | +| gnu++11 | GNU dialect of ISO C++11 | +| gnu++1y | GNU dialect of ISO C++14 Draft | +| gnu++14 | GNU dialect of ISO C++14 | +| gnu++1z | GNU dialect of ISO C++17 Draft | +| gnu++17 | GNU dialect of ISO C++17 | +| gnu++2a | GNU dialect of ISO C++20 Draft | +| gnu++20 | GNU dialect of ISO C++20 | +| gnu++2b | GNU dialect of ISO C++23 Draft | +| gnu++23 | GNU dialect of ISO C++23 | + ### Applies To ### diff --git a/website/docs/csversion.md b/website/docs/csversion.md index 81b4d1127e..1a15bd9010 100644 --- a/website/docs/csversion.md +++ b/website/docs/csversion.md @@ -1,12 +1,18 @@ +--- +title: csversion +description: Specifies the C# language level. +keywords: [premake, csversion, compiler options] +--- + Specifies the C# language level. ```lua -csversion ("value") +csversion ("version") ``` ### Parameters ### -`value` is a string specifying the C# language level. +`version` **string** - is a string specifying the C# language level. ### Applies To ### diff --git a/website/docs/customtoolnamespace.md b/website/docs/customtoolnamespace.md index c0349b218a..3298acf9c1 100644 --- a/website/docs/customtoolnamespace.md +++ b/website/docs/customtoolnamespace.md @@ -1,5 +1,10 @@ -customtoolnamespace +--- +title: customtoolnamespace +description: Sets the namespace used by custom build tools in Visual Studio .NET projects. +keywords: [premake, customtoolnamespace, visual studio, .net, msbuild, custom tool, namespace] +--- +Sets the namespace used by custom build tools in Visual Studio .NET projects. ```lua customtoolnamespace "value" ``` diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 0faf2e07a2..b6c47fadb7 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -136,6 +136,11 @@ export default { editUrl: 'https://github.com/premake/premake-core/edit/master/website/', showLastUpdateAuthor: true, showLastUpdateTime: true, + admonitions: { + keywords: ['note', 'tip', 'info', 'warning', 'danger'], + extendDefaults: true, + }, + remarkPlugins: [require('remark-admonitions')], }, blog: { blogSidebarTitle: 'Posts', From c4f5b85f5fadc3da004d2f53302a6ae7faf9d09b Mon Sep 17 00:00:00 2001 From: Robbe Beernaert Date: Tue, 2 Dec 2025 12:14:19 +0100 Subject: [PATCH 2/3] fix: removed require for unused plugin --- website/docusaurus.config.js | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index b6c47fadb7..c8073f8fdc 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -140,7 +140,6 @@ export default { keywords: ['note', 'tip', 'info', 'warning', 'danger'], extendDefaults: true, }, - remarkPlugins: [require('remark-admonitions')], }, blog: { blogSidebarTitle: 'Posts', From 9dbcad28d0edf7cfe7d14cbf195e262e2eaaca56 Mon Sep 17 00:00:00 2001 From: Robbe Beernaert Date: Fri, 5 Dec 2025 16:50:52 +0100 Subject: [PATCH 3/3] feat: added doc generate/check scripts --- website/docgenerate.mjs | 441 +++++++++++++++++++++++++++ website/docs/allmodulespublic.md | 4 +- website/docs/androidapilevel.md | 2 +- website/docs/androidapplibname.md | 2 +- website/docs/architecture.md | 50 +-- website/docs/basedir.md | 2 +- website/docs/buildaction.md | 4 +- website/docs/buildcustomizations.md | 2 +- website/docs/debugargs.md | 8 +- website/docs/debugcommand.md | 15 +- website/docs/debugconnectcommands.md | 8 +- website/docs/debugdir.md | 18 +- website/docscheck.js | 277 +++++++++++++++++ website/package.json | 4 +- 14 files changed, 799 insertions(+), 38 deletions(-) create mode 100644 website/docgenerate.mjs create mode 100644 website/docscheck.js diff --git a/website/docgenerate.mjs b/website/docgenerate.mjs new file mode 100644 index 0000000000..7d2ab86bcc --- /dev/null +++ b/website/docgenerate.mjs @@ -0,0 +1,441 @@ +import fs from "fs"; +import { ref } from "process"; +import readline from "readline"; +class Prompt { + constructor(rl) { + console.clear(); + + + this.rl = rl + + process.stdin.setRawMode(true); + process.stdin.resume(); + process.stdin.setEncoding("utf8"); + } + + // Generic helper to ask a question and assign to a property + async askAndStore(question, property) { + return new Promise(resolve => { + this.rl.question(question, answer => { + this[property] = answer.trim(); + console.clear(); + resolve(this[property]); + }); + }); + } + + async confirm(message = "Are you sure? (y/n): ") { + return new Promise(resolve => { + this.rl.question(message, answer => { + const confirmed = answer.trim().toLowerCase() === "y"; + resolve(confirmed); + }); + }); + } + async selectFromList(message, options) { + return new Promise(resolve => { + let index = 0; + + const render = () => { + console.clear(); + console.log(message); + options.forEach((opt, i) => { + if (i === index) { + console.log(`> ${opt}`); // highlight current selection + } else { + console.log(` ${opt}`); + } + }); + }; + + render(); + + const onKeyPress = (key) => { + if (key === "\u0003") { // ctrl+c + process.exit(); + } else if (key === "\r") { // enter + process.stdin.removeListener("data", onKeyPress); + resolve(options[index]); + } else if (key === "\u001b[A") { // up arrow + index = (index - 1 + options.length) % options.length; + render(); + } else if (key === "\u001b[B") { // down arrow + index = (index + 1) % options.length; + render(); + } + }; + + process.stdin.on("data", onKeyPress); + }); + } +} + +// Example specialization for documentation prompts +class DocPrompt extends Prompt { + constructor(rl) { + super(rl); + this.title = null; + this.description = null; + this.keywords = []; + } + + async askTitle() { + return await this.askAndStore("Enter the function name: ", "title"); + } + + async askDescription() { + return await this.askAndStore("Enter the description: ", "description"); + } + + async askKeywords() { + const answer = await this.askAndStore("Enter a comma separated list of keywords: ", "keywords"); + this.keywords = answer.split(",").map(k => k.trim()).filter(Boolean); + return this.keywords; + } + + async run() { + let confirmed = false; + while (!confirmed) { + await this.askTitle(); + await this.askDescription(); + await this.askKeywords(); + + console.log("\nheader:", { + title: this.title, + description: this.description, + keywords: this.keywords + }); + + confirmed = await this.confirm(); + } + } +} + +/** + * Storage class containing param info + */ +class Param { + constructor(name = null, description = null, type = null, subtype = null) { + this.name = name; + this.description = description; + this.type = type; + this.subtype = subtype; + } + getType() { + if (this.subtype === "none") { + return this.type; + } else if (this.subtype === "array") { + return `${this.type}[]`; + } + } + + getSignature() { + if (this.subtype === null) { + return this.getEnumTable(); + } + return this.getValueSignature(); + } + + getValueSignature() { + return `\`${this.name}\` **${this.getType()}** - ${this.description}`; + } + getEnumTable() { + + // Table header: use this.name as the first column title + let md = `| ${this.name} | Description |\n`; + md += `|-------------|-------------|\n`; + + // Each type value becomes a row + this.type.forEach(val => { + md += `| ${val} | |\n`; + }); + + return md; + } +} + +class ParamPrompt extends Prompt { + static PARAM_TYPES = [ + "nil", + "any", + "boolean", + "string", + "number", + "integer", + "function", + "table", + "thread", + "userdata", + "lightuserdata" + ]; + + static PARAM_SUB_TYPE = [ + "array", + "table", + "none", + ]; + constructor(rl) { + super(rl); + this.name = null; + this.description = null; + this.type = null; + this.subtype = null; + this.enumValues = null; + } + async askName() { + return await this.askAndStore("Enter the parameter name: ", "name"); + } + + async askEnumValues() { + const answer = await this.askAndStore("Enter a comma separated list of enum values: ", "enumValues"); + this.enumValues = answer.split(",").map(k => k.trim()).filter(Boolean); + this.subtype = null; + this.description = null; + this.type = null; + } + + async askDescription() { + return await this.askAndStore("Enter the parameter description: ", "description"); + } + + async askType() { + this.type = await this.selectFromList("choose an appropriate parameter type", ParamPrompt.PARAM_TYPES) + } + + async askSubType() { + this.subtype = await this.selectFromList("choose an appropriate parameter sub type", ParamPrompt.PARAM_SUB_TYPE) + } + + getParam() { + return new Param(this.name, this.description, this.type ?? this.enumValues, this.subtype) + } + async run() { + let confirmed = false; + while (!confirmed) { + await this.askName(); + if (await this.confirm("is the parameter and enum type? (y/n): ")) { + await this.askEnumValues(); + } else { + await this.askDescription(); + await this.askType(); + await this.askSubType(); + } + + console.log("param:", this.getParam()) + + confirmed = await this.confirm(); + } + } +} + + +class ParamsPrompt extends Prompt { + constructor(rl) { + super(rl); + this.params = [] + } + async run() { + let confirmed = !await this.confirm("Does this function have input parameters? (y/n): ");; + let paramPrompt = new ParamPrompt(this.rl); + while (!confirmed) { + await paramPrompt.run(); + const param = paramPrompt.getParam(); + confirmed = !await this.confirm("Are there more parameters? (y/n): "); + this.params = [...this.params, param] + } + console.log(this.params); + } +} + +class AvailabilityPrompt extends Prompt { + constructor(rl) { + super(rl); + this.availability = null; + } + async askAvailability() { + return await this.askAndStore("Pls enter the function availability: ", "availability"); + } + async run() { + let confirmed = false; + while (!confirmed) { + await this.askAvailability(); + console.log("\navailability: ", this.availability); + confirmed = await this.confirm(); + } + } +} + +class AppliesPrompt extends Prompt { + constructor(rl) { + super(rl); + this.applies = null; + } + async askApplies() { + return await this.askAndStore("Pls enter the scope the function applies to: ", "applies"); + } + async run() { + let confirmed = false; + while (!confirmed) { + await this.askApplies(); + console.log("\napplies: ", this.applies); + confirmed = await this.confirm(); + } + } +} + +class ReferencesPrompt extends Prompt { + constructor(rl) { + super(rl); + this.reference = null + this.references = []; + } + async askReference() { + return await this.askAndStore("Pls enter the function/reference name: ", "reference"); + } + async run() { + let confirmed = !await this.confirm("Are there noteworthy references (function)s? (y/n): "); + while (!confirmed) { + this.references = [...this.references, await this.askReference()]; + console.log("\nreference: ", this.availability); + confirmed = !await this.confirm("Are there more references? (y/n): "); + } + } +} + +class info { + static async prompt() { + const rl = readline.createInterface({ + input: process.stdin, + output: process.stdout + }); + const header = new DocPrompt(rl); + await header.run(); + + const params = new ParamsPrompt(rl); + await params.run(); + + const applies = new AppliesPrompt(rl); + await applies.run(); + + const availability = new AvailabilityPrompt(rl); + await availability.run(); + + const references = new ReferencesPrompt(rl); + await references.run(); + return { + header: header, + params: params, + applies: applies, + availability: availability, + references: references + } + }; +} + +class header { + /** + * + * @param {*} header + * @param {Param[]} params + */ + constructor(header, params) { + this.header = header; + this.params = params; + } + getHeader() { + return `---\r\ntitle: ${this.header.title}\r\ndescription: ${this.header.description}\r\nkeywords: [${this.header.keywords.join(', ')}]\r\n---` + } + getParams() { + if (this.params.length > 1) { + return `(${this.params + .map(p => p.name) + .filter(Boolean) // remove null/undefined + .join(", ")})`; + } else if (this.params.length === 1) { + if (this.params[0].subtype && this.params[0].subtype.toLowerCase() !== "none") { + return ` { "${this.params[0].name}" } `; + } else { + return ` ("${this.params[0].name}")`; + } + } + } + getSignature() { + return `\`\`\`lua\r\n${this.header.title}${this.getParams()}\r\n\`\`\``; + } + getSection() { + return [ + this.getHeader(), + this.header.description, + this.getSignature() + ].join("\n\n"); + } +} + +class params { + constructor(params) { + this.params = params.params; + } + getSection() { + const signatures = this.params.map((param) => param.getSignature()); + return [ + "### Parameters ###", + ...signatures + ].join("\n\n") + } +} + +class applies { + constructor(applies) { + this.applies = applies; + } + + getSection() { + return `### Applies To ###\r\n\r\n${this.applies.applies}`; + } +} + +class availability { + constructor(availability) { + this.availability = availability; + } + + getSection() { + return `### Availability ###\r\n\r\n${this.availability.availability}`; + } +} + +class references { + constructor(references) { + this.references = references.references; + } + + getReference(reference){ + return `* [${reference}](${reference.replace(" ","-")}.md)`; + } + + getReferences(){ + return this.references.map((ref) => this.getReference(ref)).join("n\n"); + } + getSection() { + return `### See Also ###\r\n\r\n${this.getReferences()}`; + } +} +/** + * store so we can later recover stdout + */ +const _stdoutSnapshot = process.stdout.write.toString(); +console.clear(); +// Example usage: + +const promptInfo = await info.prompt() + +const headerSection = new header(promptInfo.header, promptInfo.params.params).getSection(); +const paramSection = new params(promptInfo.params).getSection(); +const appliesSection = new applies(promptInfo.applies).getSection(); +const availabilitySection = new availability(promptInfo.availability).getSection(); +let sections = [headerSection, paramSection, appliesSection, availabilitySection]; +if(promptInfo.references.references.length > 0) { + sections = [...sections,,new references(promptInfo.references).getSection()] +} + +fs.writeFileSync(`docs/${promptInfo.header.title}.md`, sections.join("\n"), "utf8"); diff --git a/website/docs/allmodulespublic.md b/website/docs/allmodulespublic.md index 70a6979f8b..e98fe0960c 100644 --- a/website/docs/allmodulespublic.md +++ b/website/docs/allmodulespublic.md @@ -12,12 +12,12 @@ allmodulespublic "value" ### Parameters ### -| value | Description | +| Value | Description | | ----- | ------------------------------------------------------------- | | On | All C++ modules in the given project(s) will be public. | | Off | Not all C++ modules in the given project(s) will be public.[] | -## Applies To ### +### Applies To ### The `config` scope. diff --git a/website/docs/androidapilevel.md b/website/docs/androidapilevel.md index d1310bd52e..7a6aa76d97 100644 --- a/website/docs/androidapilevel.md +++ b/website/docs/androidapilevel.md @@ -14,7 +14,7 @@ androidapilevel(level) `level` **number** - is a number specifying the target Android API level. -## Applies To ### +### Applies To ### The `config` scope. diff --git a/website/docs/androidapplibname.md b/website/docs/androidapplibname.md index 43e11d9444..bf97cfe81a 100644 --- a/website/docs/androidapplibname.md +++ b/website/docs/androidapplibname.md @@ -16,7 +16,7 @@ By default, the project name will be used as the file name for the APK. `filename` **string** - is the new file name. -## Applies To ### +### Applies To ### The `config` scope. diff --git a/website/docs/architecture.md b/website/docs/architecture.md index 0713e6f7e5..833f105d45 100644 --- a/website/docs/architecture.md +++ b/website/docs/architecture.md @@ -12,34 +12,36 @@ architecture ("arch") ### Parameters ### -| Arch | Description | -|-------------|--------------------------------------------------| -| universal | Universal binaries supported by iOS and macOS | -| x86 | 32-bit x86 architecture | -| x86_64 | 64-bit x86 architecture | -| ARM | 32-bit ARM architecture | -| ARM64 | 64-bit ARM architecture | -| RISCV64 | 64-bit RISC-V architecture | -| loongarch64 | 64-bit LoongArch architecture | -| ppc | 32-bit PowerPC architecture | -| ppc64 | 64-bit PowerPC architecture | -| wasm32 | 32-bit WebAssembly target | -| wasm64 | 64-bit WebAssembly target | -| e2k | Elbrus 2000 architecture | -| mips64el | 64-bit MIPS little-endian architecture | -| armv5 | ARMv5 (only supported in VSAndroid projects) | -| armv7 | ARMv7 (only supported in VSAndroid projects) | -| aarch64 | AArch64 (only supported in VSAndroid projects) | -| mips | MIPS (only supported in VSAndroid projects) | +| Arch | Description | +| ----------- | -------------------------------------------------- | +| universal | Universal binaries supported by iOS and macOS | +| x86 | 32-bit x86 architecture | +| x86_64 | 64-bit x86 architecture | +| ARM | 32-bit ARM architecture | +| ARM64 | 64-bit ARM architecture | +| RISCV64 | 64-bit RISC-V architecture | +| loongarch64 | 64-bit LoongArch architecture | +| ppc | 32-bit PowerPC architecture | +| ppc64 | 64-bit PowerPC architecture | +| wasm32 | 32-bit WebAssembly target | +| wasm64 | 64-bit WebAssembly target | +| e2k | Elbrus 2000 architecture | +| mips64el | 64-bit MIPS little-endian architecture | +| armv5 | ARMv5 (only supported in VSAndroid projects) | +| armv7 | ARMv7 (only supported in VSAndroid projects) | +| aarch64 | AArch64 (only supported in VSAndroid projects) | +| mips | MIPS (only supported in VSAndroid projects) | | mips64 | 64-bit MIPS (only supported in VSAndroid projects) | +:::note Additional values that are aliases for the above: +::: -| arch | Description | -|-------|-----------------------------------------------| -| i386 | Alias for `x86` | -| amd64 | Alias for `x86_64` | -| x32 | Alias for `x86`; there is intent to deprecate | +| arch | Description | +| ----- | ------------------------------------------------ | +| i386 | Alias for `x86` | +| amd64 | Alias for `x86_64` | +| x32 | Alias for `x86`; there is intent to deprecate | | x64 | Alias for `x86_64`; there is intent to deprecate | diff --git a/website/docs/basedir.md b/website/docs/basedir.md index e24fad48b8..71a5baa5f9 100644 --- a/website/docs/basedir.md +++ b/website/docs/basedir.md @@ -1,7 +1,7 @@ --- title: basedir description: Sets the base directory for a configuration -keywords: [premake, basedir, base directory, path, configuration] +keywords: [premake, basedir, base directory, path, config] --- Sets the base directory for a configuration, from with other paths contained by the configuration will be made relative at export time. diff --git a/website/docs/buildaction.md b/website/docs/buildaction.md index 9ba393b856..9912a8b73b 100644 --- a/website/docs/buildaction.md +++ b/website/docs/buildaction.md @@ -12,7 +12,9 @@ buildaction ("action") ### Parameters ### +:::note For C/C++, `action` is the name of the MSBuild action as defined by the vcxproj format; eg: `ClCompile`, `FxCompile`, `None`, etc, and may refer to any such action available to MSBuild. +::: | Action | Description | |-----------------|----------------------------------------------------------------------------------| @@ -47,7 +49,7 @@ In C#, `action` is one of | UserControl | Treat the source file as [visual user control][2]. | :::warning -The descriptive actions such as **Component**, **Form*, and **UserControl** are only recognized by Visual Studio, and may be considered optional as Visual Studio will automatically deduce the types when it first examines the project. You only need to specify these actions to avoid unnecessary modifications to the project files on save. +The descriptive actions such as **Component**, **Form**, and **UserControl** are only recognized by Visual Studio, and may be considered optional as Visual Studio will automatically deduce the types when it first examines the project. You only need to specify these actions to avoid unnecessary modifications to the project files on save. ::: ### Applies To ### diff --git a/website/docs/buildcustomizations.md b/website/docs/buildcustomizations.md index 41d0d1bb97..5baa0e5458 100644 --- a/website/docs/buildcustomizations.md +++ b/website/docs/buildcustomizations.md @@ -1,7 +1,7 @@ --- title: buildcustomizations description: Imports custom .props files for Visual Studio. -keywords: [premake, buildcustomizations, visual studio, props, project] +keywords: [premake, buildcustomizations, visual studio, props, project configuration] --- Imports custom .props files for Visual Studio. diff --git a/website/docs/debugargs.md b/website/docs/debugargs.md index 74306bc977..97a95624aa 100644 --- a/website/docs/debugargs.md +++ b/website/docs/debugargs.md @@ -1,3 +1,9 @@ +--- +title: debugargs +description: Specifies a list of arguments to pass to the application when run under the debugger. +keywords: [premake, debugargs, debugger, arguments, visual studio, project config] +--- + Specifies a list of arguments to pass to the application when run under the debugger. ```lua @@ -10,7 +16,7 @@ In Visual Studio, this file can be overridden by a per-user configuration file ( ### Parameters ### -`args` is a Lua list of arguments to provide to the executable while debugging. +`args` **string** - is a list of arguments to provide to the executable while debugging. ### Applies To ### diff --git a/website/docs/debugcommand.md b/website/docs/debugcommand.md index 68a42d200c..08e42123fb 100644 --- a/website/docs/debugcommand.md +++ b/website/docs/debugcommand.md @@ -1,14 +1,25 @@ +--- +title: debugcommand +description: Specifies the command to launch a project's target when debugging. +keywords: [premake, debugargs, debugger, arguments, visual studio, project config] +--- + Specifies the command to launch a project's target when debugging. ```lua debugcommand ("command") ``` +:::note +In Visual Studio, this file can be overridden by a per-user configuration file (such as `ProjectName.vcproj.MYDOMAIN-MYUSERNAME.user`). +::: -In Visual Studio, this file can be overridden by a per-user configuration file (such as `ProjectName.vcproj.MYDOMAIN-MYUSERNAME.user`). Removing this file (which is done by Premake's clean action) will restore the default settings. +:::warning +Removing `ProjectName.vcproj.MYDOMAIN-MYUSERNAME.user` (which is done by Premake's clean action) will restore the default settings. +::: ### Parameters ### -`command` is the command to run to start the target. +`command` **string** - is the command to run to start the target. ### Applies To ### diff --git a/website/docs/debugconnectcommands.md b/website/docs/debugconnectcommands.md index e1b46607ae..732d4d081f 100644 --- a/website/docs/debugconnectcommands.md +++ b/website/docs/debugconnectcommands.md @@ -1,3 +1,9 @@ +--- +title: debugconnectcommands +description: Specifies commands to be executed upon connection of the debugger to a remote process. +keywords: [premake, debugconnectcommands, debugger, commands, visual studio, project config] +--- + Specifies commands to be executed upon connection of the debugger to a remote process. ```lua @@ -6,7 +12,7 @@ debugconnectcommands { "commands" } ### Parameters ### -`commands` is a list of commands to execute. +`commands` **string[]** - is a list of commands to execute. ### Applies To ### diff --git a/website/docs/debugdir.md b/website/docs/debugdir.md index 0c1cb04bb6..4c1d183c51 100644 --- a/website/docs/debugdir.md +++ b/website/docs/debugdir.md @@ -1,12 +1,26 @@ +--- +title: debugdir +description: Specifies commands to be executed upon connection of the debugger to a remote process. +keywords: [premake, debugdir, debugger, commands, visual studio, project config] +--- + Sets the working directory for the integrated debugger. ```lua debugdir "path" ``` -Note that this settings is not implemented for Xcode, which requires a per-user configuration file in order to make it work. +:::note +this settings is not implemented for Xcode, which requires a per-user configuration file in order to make it work. +::: + +:::note +In Visual Studio, this file can be overridden by a per-user configuration file (such as `ProjectName.vcproj.MYDOMAIN-MYUSERNAME.user`). +::: -In Visual Studio, this file can be overridden by a per-user configuration file (such as `ProjectName.vcproj.MYDOMAIN-MYUSERNAME.user`). Removing this file (which is done by Premake's clean action) will restore the default settings. +:::warning +Removing `ProjectName.vcproj.MYDOMAIN-MYUSERNAME.user` (which is done by Premake's clean action) will restore the default settings. +::: ### Parameters ### diff --git a/website/docscheck.js b/website/docscheck.js new file mode 100644 index 0000000000..b1bdfb4d35 --- /dev/null +++ b/website/docscheck.js @@ -0,0 +1,277 @@ +const { Console } = require("console"); +const fs = require("fs"); +const path = require("path"); + +class FormatClass { + /** + * Validate either a single check or an array of checks + * @param {Function|Object[]} checkFnOrArray - single function or array of {fn, value, msg} + * @param {any} value - value to pass if single function + * @param {string} errorMessage - error message if single function + * @returns {boolean} true if all checks pass, false if any fail + */ + static validate(checkFnOrArray, value, errorMessage) { + // Case 1: single function + if (typeof checkFnOrArray === "function") { + if (!checkFnOrArray(value)) { + console.error(errorMessage); + return false; + } + return true; + } + + // Case 2: array of objects + if (Array.isArray(checkFnOrArray)) { + let allValid = true; + for (const { fn, value, msg } of checkFnOrArray) { + if (!fn(value)) { + console.error(msg); + allValid = false; + } + } + return allValid; + } + + throw new Error("Invalid argument passed to FormatClass.validate"); + } +} + +class documentationfiles { + + /** + * this function retrieves all the documentationfiles that are functions + * @param {string} directory directory to check + * @returns a list of all the documentation files + */ + static getFunctionDocs(directory = "docs") { + const files = fs.readdirSync(directory); + + // Regex: lowercase letters, numbers, underscores, hyphens, ending with .md + const validPattern = /^[a-z0-9_-]+\.md$/; + + return files.filter(file => validPattern.test(file)); + } +} + +class region { + getRegionRegex(name) { + const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + + return new RegExp( + `###\\s*${escapedName}\\s*###([\\s\\S]*?)(?=###\\s.*?###|$)`, + "i" + ); + } + constructor(inputText, region) { + const regex = this.getRegionRegex(region) + const match = inputText.match(regex); + if (match && match[1]) + this.regionText = match[1].trim() + } + get() { + return this.regionText; + } +} + +class HeaderCheck { + /** + * + * @param {string} inputText + * @param {string} filename + */ + constructor(inputText, filename) { + this.inputText = inputText; + this.filename = filename; + } + + extractBlock() { + const blockRegex = /---([\s\S]*?)---/; + const match = this.inputText.match(blockRegex); + return match ? match[1].trim() : null; + } + + /** + * this function extracts the header from the input text + * @param {string} + */ + extract() { + const block = this.extractBlock(); + + if (block === null) return null; + + const titleMatch = block.match(/title:\s*(.+)/i); + const descMatch = block.match(/description:\s*(.+)/i); + const keywordsMatch = block.match(/keywords:\s*\[([^\]]*)\]/i); + + if (!titleMatch || !descMatch || !keywordsMatch) return null; + + return { + title: titleMatch[1].trim(), + description: descMatch[1].trim(), + keywords: keywordsMatch[1].split(",").map(k => k.trim()) + }; + } + + check_header = header_obj => header_obj !== null; + check_title = header_obj => header_obj.title != null; + check_keywords = header_obj => header_obj.keywords != null; + check_description = header_obj => header_obj.description != null; + check_title_name = header_obj => (header_obj.title + ".md") === this.filename; + check() { + const header_obj = this.extract(); + this.header = header_obj; + return FormatClass.validate([ + { + //CHECK HEADER EXISTS + fn: this.check_header, + value: header_obj, + msg: "[MD] Error: missing required header block.\nExpected format:\n---\ntitle: \ndescription: \nkeywords: []\n---" + }, + { + //CHEK TITLE EXISTS + fn: this.check_title, + value: header_obj, + msg: "[MD] Error: header is missing a title field." + }, + { + fn: this.check_keywords, + value: header_obj, + msg: "[MD] Error: header is missing a keywords field." + }, + { + fn: this.check_title_name, + value: header_obj, + msg: "[MD] Error: header title and filename must match" + } + ]); + } +} + +class ParamsCheck { + constructor(inputText) { + this.region = new region(inputText, "Parameters"); + this.params = this.parse(); + } + + // --- Core parsing --- + parse() { + const content = this.region.get(); + if (!content) return null; + return content.split(/\r?\n/).filter(Boolean); + } + + // --- Validation functions --- + check_region_exists(content) { + return !!content; + } + + check_inline_format(line) { + const regex = /`([^`]+)`\s+\*\*([^\*]+)\*\*\s*-\s*(.+)/; + return regex.test(line); + } + + check_table_row(line) { + const regex = /^\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|$/; + const match = line.match(regex); + if (!match) return false; + + const name = match[1].trim(); + const description = match[2].trim(); + + // Separator rows are valid + if (/^-+$/.test(name) && /^-+$/.test(description)) return true; + + return !!(name && description); + } + + check_encapsulated_comment(line) { + + const oneLine = /^:::\s*([a-zA-Z0-9_-]+)\s+(.+?):::$/; + if (oneLine.test(line)) return true; + + //multiline blocks + if (/^:::\s*comment\b/.test(line)) return true; + if (/^:::\s*$/.test(line)) return true; + + return false; + } + + check() { + return FormatClass.validate([ + { + // Region must exist + fn: this.check_region_exists, + value: this.params, + msg: "[MD] Error: missing required Parameters region.\nExpected format:\n### Parameters ###\n`` **** - \nOR\n| | |\nOR\n:::: ::::" + }, + { + // Inline params + fn: () => this.params.every(line => + !line.trim() || this.check_inline_format(line) + ), + value: this.params, + msg: "[MD] Error: inline parameter must follow format:\n`` **** - " + }, + { + // Table rows + fn: () => this.params.every(line => + !line.trim() || this.check_table_row(line) + ), + value: this.params, + msg: "[MD] Error: table row must follow format:\n| | |" + }, + { + // Encapsulated comments + fn: () => this.params.every(line => + !line.trim() || this.check_encapsulated_comment(line) + ), + value: this.params, + msg: "[MD] Error: encapsulated comment must follow format:\n::: :::\nOr multiline:\n:::comment\ntext...\n:::" + } + ]); + } +} + +class AvailabilityCheck { + constructor(inputText) { + this.region = new region(inputText, "Availability"); + } + + check() { + if(this.region.get() === null){ + return false; + } + // Only allow plain text lines (no markdown headings, no code fences) + return this.region.get().split(/\r?\n/).filter(l => l.trim() !== "").every(line => + !/^#{1,6}\s/.test(line) && !line.startsWith("```") + ); + } +} + + + +const functiondocs = documentationfiles.getFunctionDocs(); + +for (const doc of functiondocs) { + const filePath = path.join(__dirname, "docs", doc); + const content = fs.readFileSync(filePath, "utf8"); + + const headerChecker = new HeaderCheck(content, doc); + + if (!headerChecker.check()) { + console.error(`[MD] ${doc}: invalid header section.`); + return; + } + const paramsChecker = new ParamsCheck(content); + + if (!paramsChecker.check()) { + console.error(`[MD] ${doc}: invalid parameters section.`); + return; + } + + const availabilityChecker = new AvailabilityCheck(content); + if (!availabilityChecker.check()) { + console.error(`[MD] ${doc}: invalid parameters section.`); + return; + } +} diff --git a/website/package.json b/website/package.json index f6b138bae2..f4532009e7 100644 --- a/website/package.json +++ b/website/package.json @@ -9,7 +9,9 @@ "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "serve": "docusaurus serve", - "clear": "docusaurus clear" + "clear": "docusaurus clear", + "check": "node docscheck.js", + "new" :"node docgenerate.mjs" }, "dependencies": { "@docusaurus/core": "3.5.2",