From b642217d29895488804c93e80549ef94443f09b7 Mon Sep 17 00:00:00 2001 From: Manjunath Beli Date: Tue, 25 Feb 2025 15:07:54 -0600 Subject: [PATCH 1/3] Changes from BrooksV --- README.md | 64 ++++++++++++++++++++++++----- project.json | 5 ++- src/private/CopyProjectResource.ps1 | 19 +++++++-- src/resources/ProjectTemplate.json | 1 + src/resources/Schema-Build.json | 3 ++ 5 files changed, 76 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8d12aa7..cc69031 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,6 @@ Whether you're creating simple or robust modules, ModuleTools streamlines the pr [![ModuleTools@PowerShell Gallery][BadgeIOCount]][PSGalleryLink] ![WorkFlow Status][WorkFlowStatus] - - The structure of the ModuleTools module is meticulously designed according to PowerShell best practices for module development. While some design decisions may seem unconventional, they are made to ensure that ModuleTools and the process of building modules remain straightforward and easy to manage. > [!IMPORTANT] @@ -28,7 +26,7 @@ The structure of the ModuleTools module is meticulously designed according to Po Install-Module -Name ModuleTools ``` -> Note: ModuleTolls is still in early devleopment phase and lot of changes are expected. Please read through [ChangeLog](/CHANGELOG.md) for all updates. +> Note: ModuleTolls is still in early development phase and lot of changes are expected. Please read through [ChangeLog](/CHANGELOG.md) for all updates. ## ๐Ÿงต Design @@ -62,8 +60,6 @@ Generated module is stored in dist folder, you can easily import it or publish i โ””โ”€โ”€ ๏…› TestModule.psm1 ``` - - ### Project JSON File The `project.json` file contains all the important details about your module and is used during the module build. It should comply with a specific schema. You can refer to the sample `project-sample.json` file in the `example` directory for guidance. @@ -72,9 +68,43 @@ Run `New-MTModule` to generate the scaffolding; this will also create the `proje ### Src Folder - - Place all your functions in the `private` and `public` folders within the `src` directory. - - All functions in the `public` folder are exported during the module build. - - All functions in the `private` folder are accessible internally within the module but are not exposed outside the module. +- Place all your functions in the `private` and `public` folders within the `src` directory. +- All functions in the `public` folder are exported during the module build. +- All functions in the `private` folder are accessible internally within the module but are not exposed outside the module. +- Contents of the `src/resources` folder, including any subfolder, will included in the `dist` folder during the module build. + +#### resources Folder + +The `resources` folder within the `src` directory is intended for including any additional resources required by your module. This can include files such as: + +- **Configuration files**: Store any JSON, XML, or other configuration files needed by your module. +- **Script files**: Place any scripts that are used by your functions or modules, but are not directly part of the public or private functions. +- **Documentation files**: Include any supplementary documentation that supports the usage or development of the module. +- **Data files**: Store any data files that are used by your module, such as CSV or JSON files. +- **Subfolder**: Include any additional folders and their content to be included with the module, such as dependant Modules, APIs, DLLs, etc... organized by a subfolder. + +When the module is built, the contents of the `src/resources` folder will be copied directly to the `dist` folder. If the `src/resources` folder contains any subfolders, those subfolders and their contents will also be included in the `dist` folder, ensuring that all necessary files are available for the module to function correctly. + +How the resources folder gets copied to the "OutputModuleDir" folder will depends on the "ResourceCopyMode" project setting. When missing or set to "Folder", the resources folder will be copied. When "ResourceCopyMode" is set to "Content", then only the content of the resources folder will be copied. + +Leave `src\resources` empty if there is no need to include any additional content in the `dist` folder. + +An example of the module build where resources were included: + +```powershell +dist +โ””โ”€โ”€ TestModule + โ”œโ”€โ”€ TestModule.psd1 + โ”œโ”€โ”€ TestModule.psm1 + โ”œโ”€โ”€ config.json + โ”œโ”€โ”€ additionalScript.ps1 + โ”œโ”€โ”€ helpDocumentation.md + โ”œโ”€โ”€ sampleData.csv + โ””โ”€โ”€ subfolder + โ”œโ”€โ”€ subConfig.json + โ”œโ”€โ”€ subScript.ps1 + โ””โ”€โ”€ subData.csv +``` ### Tests Folder @@ -97,6 +127,11 @@ New-MTModule ~/Work `ModuleTools` is designed so that you don't need any additional tools like `make` or `psake` to run the build commands. There's no need to maintain complex `build.ps1` files or sample `.psd1` files. Simply follow the structure outlined above, and you can run `Invoke-MTBuild` to build the module. The output will be saved in the `dist` folder, ready for distribution. +The Invoke-MTBuild CmdLet includes a step where the resources folder and/or it's contents are copied to the "OutputModuleDir" folder. This is controlled by the optional "ResourceCopyMode" project setting. + +If "ResourceCopyMode" = 'Folder or if it's missing, the entire resources folder gets copied to the "OutputModuleDir" folder. +If "ResourceCopyMode" = 'Content', only the content of the resources folder gets copied to the "OutputModuleDir" folder. + ```powershell # From the Module root Invoke-MTBuild @@ -126,7 +161,15 @@ A simple command to update the module version by modifying the values in `projec ## Advanced - Use it in Github Actions -This is not required for local module builds, if you are running github actions, use below template to test, build and publish module with ease. +This is not required for local module builds, if you are running github actions, use the following yaml workflow template to test, build and publish module which helps to automate the process of: + +1. Checking out the repository code. +1. Installing the `ModuleTools` module from the PowerShell Gallery. +1. Building the module. +1. Running Pester tests. +1. Publishing the module to a specified repository. + +This allows for seamless and automated management of your PowerShell module, ensuring consistency and reliability in your build, test, and release processes. ```yaml name: Build, Test and Publish @@ -154,6 +197,7 @@ jobs: - name: Run Pester Tests run: Invoke-MTTest shell: pwsh + - name: Publish Package to Github run: | Publish-PSResource -Path ./dist/YourModule -Repository SomeRepository -ApiKey $Env:ApiKey @@ -181,4 +225,4 @@ This project is licensed under the MIT License. See the LICENSE file for details [BadgeIOCount]: https://img.shields.io/powershellgallery/dt/ModuleTools?label=ModuleTools%40PowerShell%20Gallery [PSGalleryLink]: https://www.powershellgallery.com/packages/ModuleTools/ -[WorkFlowStatus]: https://img.shields.io/github/actions/workflow/status/belibug/ModuleTools/Tests.yml +[WorkFlowStatus]: https://img.shields.io/github/actions/workflow/status/belibug/ModuleTools/Tests.yml \ No newline at end of file diff --git a/project.json b/project.json index ee220ab..9c3f7bf 100644 --- a/project.json +++ b/project.json @@ -1,7 +1,8 @@ { "ProjectName": "ModuleTools", "Description": "ModuleTools is a versatile, standalone PowerShell module builder. Create anything from simple to robust modules with ease. Built for CICD and Automation.", - "Version": "0.0.9", + "Version": "0.0.10", + "ResourceCopyMode": "Folder", "Manifest": { "Author": "Manjunath Beli", "PowerShellHostVersion": "7.4", @@ -18,4 +19,4 @@ "Verbosity": "Detailed" } } -} +} \ No newline at end of file diff --git a/src/private/CopyProjectResource.ps1 b/src/private/CopyProjectResource.ps1 index 99f1868..1591096 100644 --- a/src/private/CopyProjectResource.ps1 +++ b/src/private/CopyProjectResource.ps1 @@ -1,11 +1,22 @@ function Copy-ProjectResource { $data = Get-MTProjectInfo $resFolder = [System.IO.Path]::Join($data.ProjectRoot, 'src', 'resources') - if (Test-Path $resFolder) { - if (Get-ChildItem $resFolder -ErrorAction SilentlyContinue) { - Write-Verbose 'Files found in resource folder, Copying resource folder content' - Copy-Item -Path $resFolder -Destination ($data.OutputModuleDir) -Recurse -Force -ErrorAction Stop + if ($data.ResourceCopyMode -eq 'Content') { + # Copy the resources folder content to the OutputModuleDir + $items = Get-ChildItem -Path $resFolder -ErrorAction SilentlyContinue + if ($items) { + Write-Verbose 'Files found in resource folder, copying resource folder content' + foreach ($item in $items) { + Copy-Item -Path $item.FullName -Destination ($data.OutputModuleDir) -Recurse -Force -ErrorAction Stop + } + } + } else { + # Copy the resources folder to the OutputModuleDir + if (Get-ChildItem $resFolder -ErrorAction SilentlyContinue) { + Write-Verbose 'Files found in resource folder, Copying resource folder' + Copy-Item -Path $resFolder -Destination ($data.OutputModuleDir) -Recurse -Force -ErrorAction Stop + } } } } \ No newline at end of file diff --git a/src/resources/ProjectTemplate.json b/src/resources/ProjectTemplate.json index c2c04d9..3829d00 100644 --- a/src/resources/ProjectTemplate.json +++ b/src/resources/ProjectTemplate.json @@ -2,6 +2,7 @@ "ProjectName": "", "Description": "", "Version": "", + "ResourceCopyMode": "", "Manifest": { "Author": "", "PowerShellHostVersion": "", diff --git a/src/resources/Schema-Build.json b/src/resources/Schema-Build.json index 4104722..b8d54f7 100644 --- a/src/resources/Schema-Build.json +++ b/src/resources/Schema-Build.json @@ -12,6 +12,9 @@ "Version": { "type": "string" }, + "ResourceCopyMode": { + "type": "string" + }, "Manifest": { "type": "object", "properties": { From 42b652727b774a2bb5efb15866b68b985e9b9387 Mon Sep 17 00:00:00 2001 From: Manjunath Beli Date: Tue, 11 Mar 2025 12:50:39 -0500 Subject: [PATCH 2/3] resource files handling and readme update --- CHANGELOG.md | 10 ++++++++-- README.md | 14 ++++---------- project.json | 2 +- src/private/CopyProjectResource.ps1 | 3 ++- src/resources/ProjectTemplate.json | 2 +- src/resources/Schema-Build.json | 4 ++-- 6 files changed, 18 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b5e5775..e613eb3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,15 @@ All notable changes to this project will be documented in this file. -## Inprogress +## [1.0.0] -- Updated `ProjecUri` typo to `ProjectUri` in all places. This should work properly for all new module invokes. +### Added + +- New optional project setting `copyResourcesToModuleRoot`. Setting to true places resource files in the root directory of module. Default is `false` to provide backward compatibility. Thanks to @BrooksV + +### Fixed + +- **BREAKING CHANGE**: Typo corrected: ProjecUri to ProjectUri. Existing projects require manual update. ## [0.0.9] - 2024-07-17 diff --git a/README.md b/README.md index cc69031..633d9e2 100644 --- a/README.md +++ b/README.md @@ -71,9 +71,9 @@ Run `New-MTModule` to generate the scaffolding; this will also create the `proje - Place all your functions in the `private` and `public` folders within the `src` directory. - All functions in the `public` folder are exported during the module build. - All functions in the `private` folder are accessible internally within the module but are not exposed outside the module. -- Contents of the `src/resources` folder, including any subfolder, will included in the `dist` folder during the module build. +- Contents of the `src/resources` folder will be handled based on setting `copyResourcesToModuleRoot` -#### resources Folder +#### Resources Folder The `resources` folder within the `src` directory is intended for including any additional resources required by your module. This can include files such as: @@ -83,13 +83,12 @@ The `resources` folder within the `src` directory is intended for including any - **Data files**: Store any data files that are used by your module, such as CSV or JSON files. - **Subfolder**: Include any additional folders and their content to be included with the module, such as dependant Modules, APIs, DLLs, etc... organized by a subfolder. -When the module is built, the contents of the `src/resources` folder will be copied directly to the `dist` folder. If the `src/resources` folder contains any subfolders, those subfolders and their contents will also be included in the `dist` folder, ensuring that all necessary files are available for the module to function correctly. -How the resources folder gets copied to the "OutputModuleDir" folder will depends on the "ResourceCopyMode" project setting. When missing or set to "Folder", the resources folder will be copied. When "ResourceCopyMode" is set to "Content", then only the content of the resources folder will be copied. +By default, resource files from `src/resources` go into `dist/resources`. To place them directly in dist (avoiding the resources subfolder), set `copyResourcesToModuleRoot` to `true`. This provides greater control in certain deployment scenarios where resources files are preferred in module root directory. Leave `src\resources` empty if there is no need to include any additional content in the `dist` folder. -An example of the module build where resources were included: +An example of the module build where resources were included and `copyResourcesToModuleRoot` is set to true. ```powershell dist @@ -127,11 +126,6 @@ New-MTModule ~/Work `ModuleTools` is designed so that you don't need any additional tools like `make` or `psake` to run the build commands. There's no need to maintain complex `build.ps1` files or sample `.psd1` files. Simply follow the structure outlined above, and you can run `Invoke-MTBuild` to build the module. The output will be saved in the `dist` folder, ready for distribution. -The Invoke-MTBuild CmdLet includes a step where the resources folder and/or it's contents are copied to the "OutputModuleDir" folder. This is controlled by the optional "ResourceCopyMode" project setting. - -If "ResourceCopyMode" = 'Folder or if it's missing, the entire resources folder gets copied to the "OutputModuleDir" folder. -If "ResourceCopyMode" = 'Content', only the content of the resources folder gets copied to the "OutputModuleDir" folder. - ```powershell # From the Module root Invoke-MTBuild diff --git a/project.json b/project.json index 9c3f7bf..143a9a2 100644 --- a/project.json +++ b/project.json @@ -2,7 +2,7 @@ "ProjectName": "ModuleTools", "Description": "ModuleTools is a versatile, standalone PowerShell module builder. Create anything from simple to robust modules with ease. Built for CICD and Automation.", "Version": "0.0.10", - "ResourceCopyMode": "Folder", + "copyResourcesToModuleRoot": false, "Manifest": { "Author": "Manjunath Beli", "PowerShellHostVersion": "7.4", diff --git a/src/private/CopyProjectResource.ps1 b/src/private/CopyProjectResource.ps1 index 1591096..5a15de3 100644 --- a/src/private/CopyProjectResource.ps1 +++ b/src/private/CopyProjectResource.ps1 @@ -2,7 +2,8 @@ function Copy-ProjectResource { $data = Get-MTProjectInfo $resFolder = [System.IO.Path]::Join($data.ProjectRoot, 'src', 'resources') if (Test-Path $resFolder) { - if ($data.ResourceCopyMode -eq 'Content') { + ## Copy to root folder instead of creating Resource Folder in module root + if ($data.copyResourcesToModuleRoot) { # Copy the resources folder content to the OutputModuleDir $items = Get-ChildItem -Path $resFolder -ErrorAction SilentlyContinue if ($items) { diff --git a/src/resources/ProjectTemplate.json b/src/resources/ProjectTemplate.json index 3829d00..4259bc0 100644 --- a/src/resources/ProjectTemplate.json +++ b/src/resources/ProjectTemplate.json @@ -2,7 +2,7 @@ "ProjectName": "", "Description": "", "Version": "", - "ResourceCopyMode": "", + "copyResourcesToModuleRoot": false, "Manifest": { "Author": "", "PowerShellHostVersion": "", diff --git a/src/resources/Schema-Build.json b/src/resources/Schema-Build.json index b8d54f7..56dd3b6 100644 --- a/src/resources/Schema-Build.json +++ b/src/resources/Schema-Build.json @@ -12,8 +12,8 @@ "Version": { "type": "string" }, - "ResourceCopyMode": { - "type": "string" + "copyResourcesToModuleRoot": { + "type": "boolean" }, "Manifest": { "type": "object", From 228a5bf45a5122f10e36c12887c3874fe4822844 Mon Sep 17 00:00:00 2001 From: Manjunath Beli <61643561+belibug@users.noreply.github.com> Date: Tue, 11 Mar 2025 12:56:22 -0500 Subject: [PATCH 3/3] Update CHANGELOG.md --- CHANGELOG.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e613eb3..faceef8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,11 @@ All notable changes to this project will be documented in this file. -## [1.0.0] +## [1.0.0] - 2025-03-11 ### Added -- New optional project setting `copyResourcesToModuleRoot`. Setting to true places resource files in the root directory of module. Default is `false` to provide backward compatibility. Thanks to @BrooksV +- New optional project setting `copyResourcesToModuleRoot`. Setting to true places resource files in the root directory of module. Default is `false` to provide backward compatibility. Thanks to @[BrooksV](https://github.com/BrooksV) ### Fixed @@ -53,4 +53,4 @@ All notable changes to this project will be documented in this file. ### Added - First release to `psgallery` -- All basic functionality of Module is ready \ No newline at end of file +- All basic functionality of Module is ready