From 2c042a268138c7bd928f8934b77c1ae716ca52f6 Mon Sep 17 00:00:00 2001 From: Alistair Chapman Date: Tue, 4 Jul 2017 03:27:13 +1000 Subject: [PATCH] Adding documentation, build scripts and metadata --- .gitignore | 6 +- LICENSE | 21 ++ ReleaseNotes.md | 3 + build.cake | 166 ++++++++++++++ build.ps1 | 228 ++++++++++++++++++++ build.sh | 131 +++++++++++ docfx/.gitignore | 9 + docfx/api/.gitignore | 4 + docfx/api/index.md | 5 + docfx/doc/contributing.md | 21 ++ docfx/doc/intro.md | 50 +++++ docfx/doc/packages.md | 17 ++ docfx/doc/settings.md | 48 +++++ docfx/doc/toc.yml | 8 + docfx/docfx.json | 80 +++++++ docfx/index.md | 10 + docfx/toc.yml | 6 + helpers.cake | 49 +++++ src/Cake.AzCopy/AzCopySettingsExtensions.cs | 5 +- 19 files changed, 864 insertions(+), 3 deletions(-) create mode 100644 LICENSE create mode 100644 ReleaseNotes.md create mode 100644 build.cake create mode 100644 build.ps1 create mode 100755 build.sh create mode 100644 docfx/.gitignore create mode 100644 docfx/api/.gitignore create mode 100644 docfx/api/index.md create mode 100644 docfx/doc/contributing.md create mode 100644 docfx/doc/intro.md create mode 100644 docfx/doc/packages.md create mode 100644 docfx/doc/settings.md create mode 100644 docfx/doc/toc.yml create mode 100644 docfx/docfx.json create mode 100644 docfx/index.md create mode 100644 docfx/toc.yml create mode 100644 helpers.cake diff --git a/.gitignore b/.gitignore index 7bd3b52..9fc25bc 100644 --- a/.gitignore +++ b/.gitignore @@ -276,8 +276,10 @@ __pycache__/ *.pyc # Cake - Uncomment if you are using it -# tools/** -# !tools/packages.config +!tools/Modules/packages.config +!tools/packages.config +tools/** +dist/** # Telerik's JustMock configuration file *.jmconfig diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5663e42 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2017 Alistair Chapman + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/ReleaseNotes.md b/ReleaseNotes.md new file mode 100644 index 0000000..4207b09 --- /dev/null +++ b/ReleaseNotes.md @@ -0,0 +1,3 @@ +# 0.1.0 + +- Initial release \ No newline at end of file diff --git a/build.cake b/build.cake new file mode 100644 index 0000000..724b725 --- /dev/null +++ b/build.cake @@ -0,0 +1,166 @@ +#tool "nuget:?package=GitVersion.CommandLine" +#load "helpers.cake" +#tool nuget:?package=docfx.console +#addin nuget:?package=Cake.DocFx + +/////////////////////////////////////////////////////////////////////////////// +// ARGUMENTS +/////////////////////////////////////////////////////////////////////////////// + +var target = Argument("target", "Default"); +var configuration = Argument("configuration", "Release"); +var buildFrameworks = Argument("frameworks", "netstandard1.6;net45"); + +/////////////////////////////////////////////////////////////////////////////// +// GLOBAL VARIABLES +/////////////////////////////////////////////////////////////////////////////// + +var solutionPath = File("./src/Cake.AzCopy.sln"); +var projects = GetProjects(solutionPath, configuration); +var artifacts = "./dist/"; +var testResultsPath = MakeAbsolute(Directory(artifacts + "./test-results")); +GitVersion versionInfo = null; +var frameworks = buildFrameworks.Split(new[] { ";", ","}, StringSplitOptions.RemoveEmptyEntries); + +/////////////////////////////////////////////////////////////////////////////// +// SETUP / TEARDOWN +/////////////////////////////////////////////////////////////////////////////// + +Setup(ctx => +{ + // Executed BEFORE the first task. + Information("Running tasks..."); + versionInfo = GitVersion(); + Information("Building for version {0}", versionInfo.FullSemVer); + Verbose("Building for " + string.Join(", ", frameworks)); +}); + +Teardown(ctx => +{ + // Executed AFTER the last task. + Information("Finished running tasks."); +}); + +/////////////////////////////////////////////////////////////////////////////// +// TASK DEFINITIONS +/////////////////////////////////////////////////////////////////////////////// + +Task("Clean") + .Does(() => +{ + // Clean solution directories. + foreach(var path in projects.AllProjectPaths) + { + Information("Cleaning {0}", path); + CleanDirectories(path + "/**/bin/" + configuration); + CleanDirectories(path + "/**/obj/" + configuration); + } + Information("Cleaning common files..."); + CleanDirectory(artifacts); +}); + +Task("Restore") + .Does(() => +{ + // Restore all NuGet packages. + Information("Restoring solution..."); + //NuGetRestore(solutionPath); + foreach (var project in projects.AllProjectPaths) { + DotNetCoreRestore(project.FullPath); + } +}); + +Task("Build") + .IsDependentOn("Clean") + .IsDependentOn("Restore") + .Does(() => +{ + Information("Building solution..."); + foreach(var framework in frameworks) { + foreach (var project in projects.SourceProjectPaths) { + var settings = new DotNetCoreBuildSettings { + Framework = framework, + Configuration = configuration, + NoIncremental = true, + }; + DotNetCoreBuild(project.FullPath, settings); + } + } + +}); + +Task("Run-Unit-Tests") + .IsDependentOn("Build") + .Does(() => +{ + CreateDirectory(testResultsPath); + if (projects.TestProjects.Any()) { + + var settings = new DotNetCoreTestSettings { + Configuration = configuration + }; + + foreach(var project in projects.TestProjects) { + DotNetCoreTest(project.Path.FullPath, settings); + } + } +}); + +Task("Generate-Docs").Does(() => { + DocFxBuild("./docfx/docfx.json"); + Zip("./docfx/_site/", artifacts + "/docfx.zip"); +}); + +Task("Post-Build") + .IsDependentOn("Build") + .IsDependentOn("Run-Unit-Tests") + .IsDependentOn("Generate-Docs") + .Does(() => +{ + CreateDirectory(artifacts + "build"); + CreateDirectory(artifacts + "modules"); + foreach (var project in projects.SourceProjects) { + CreateDirectory(artifacts + "build/" + project.Name); + foreach (var framework in frameworks) { + var frameworkDir = artifacts + "build/" + project.Name + "/" + framework; + CreateDirectory(frameworkDir); + var files = GetFiles(project.Path.GetDirectory() + "/bin/" + configuration + "/" + framework + "/" + project.Name +".*"); + CopyFiles(files, frameworkDir); + } + } +}); + +Task("NuGet") + .IsDependentOn("Post-Build") + .Does(() => +{ + CreateDirectory(artifacts + "package"); + Information("Building NuGet package"); + var versionNotes = ParseAllReleaseNotes("./ReleaseNotes.md").FirstOrDefault(v => v.Version.ToString() == versionInfo.MajorMinorPatch); + var content = GetContent(frameworks, projects, configuration); + var settings = new NuGetPackSettings { + Id = "Cake.AzCopy", + Version = versionInfo.NuGetVersionV2, + Title = "Cake.AzCopy", + Authors = new[] { "Alistair Chapman" }, + Owners = new[] { "achapman", "cake-contrib" }, + Description = "A simple Cake addin powered by AzCopy for uploading and downloading to/from Azure Storage (including Blob, Table and Files)", + ReleaseNotes = versionNotes != null ? versionNotes.Notes.ToList() : new List(), + Summary = "A simple Cake addin for AzCopy.", + ProjectUrl = new Uri("https://github.com/agc93/Cake.AzCopy"), + IconUrl = new Uri("https://cdn.rawgit.com/cake-contrib/graphics/a5cf0f881c390650144b2243ae551d5b9f836196/png/cake-contrib-medium.png"), + LicenseUrl = new Uri("https://raw.githubusercontent.com/agc93/Cake.AzCopy/master/LICENSE"), + Copyright = "Alistair Chapman 2017", + Tags = new[] { "cake", "build", "script", "azure", "azcopy" }, + OutputDirectory = artifacts + "/package", + Files = content, + //KeepTemporaryNuSpecFile = true + }; + + NuGetPack(settings); +}); + +Task("Default") + .IsDependentOn("NuGet"); + +RunTarget(target); diff --git a/build.ps1 b/build.ps1 new file mode 100644 index 0000000..7495727 --- /dev/null +++ b/build.ps1 @@ -0,0 +1,228 @@ +########################################################################## +# This is the Cake bootstrapper script for PowerShell. +# This file was downloaded from https://github.com/cake-build/resources +# Feel free to change this file to fit your needs. +########################################################################## + +<# + +.SYNOPSIS +This is a Powershell script to bootstrap a Cake build. + +.DESCRIPTION +This Powershell script will download NuGet if missing, restore NuGet tools (including Cake) +and execute your Cake build script with the parameters you provide. + +.PARAMETER Script +The build script to execute. +.PARAMETER Target +The build script target to run. +.PARAMETER Configuration +The build configuration to use. +.PARAMETER Verbosity +Specifies the amount of information to be displayed. +.PARAMETER Experimental +Tells Cake to use the latest Roslyn release. +.PARAMETER WhatIf +Performs a dry run of the build script. +No tasks will be executed. +.PARAMETER Mono +Tells Cake to use the Mono scripting engine. +.PARAMETER SkipToolPackageRestore +Skips restoring of packages. +.PARAMETER ScriptArgs +Remaining arguments are added here. + +.LINK +http://cakebuild.net + +#> + +[CmdletBinding()] +Param( + [string]$Script = "build.cake", + [string]$Target = "Default", + [ValidateSet("Release", "Debug")] + [string]$Configuration = "Release", + [ValidateSet("Quiet", "Minimal", "Normal", "Verbose", "Diagnostic")] + [string]$Verbosity = "Verbose", + [switch]$Experimental, + [Alias("DryRun","Noop")] + [switch]$WhatIf, + [switch]$Mono, + [switch]$SkipToolPackageRestore, + [Parameter(Position=0,Mandatory=$false,ValueFromRemainingArguments=$true)] + [string[]]$ScriptArgs +) + +[Reflection.Assembly]::LoadWithPartialName("System.Security") | Out-Null +function MD5HashFile([string] $filePath) +{ + if ([string]::IsNullOrEmpty($filePath) -or !(Test-Path $filePath -PathType Leaf)) + { + return $null + } + + [System.IO.Stream] $file = $null; + [System.Security.Cryptography.MD5] $md5 = $null; + try + { + $md5 = [System.Security.Cryptography.MD5]::Create() + $file = [System.IO.File]::OpenRead($filePath) + return [System.BitConverter]::ToString($md5.ComputeHash($file)) + } + finally + { + if ($file -ne $null) + { + $file.Dispose() + } + } +} + +Write-Host "Preparing to run build script..." + +if(!$PSScriptRoot){ + $PSScriptRoot = Split-Path $MyInvocation.MyCommand.Path -Parent +} + +$TOOLS_DIR = Join-Path $PSScriptRoot "tools" +$ADDINS_DIR = Join-Path $TOOLS_DIR "Addins" +$MODULES_DIR = Join-Path $TOOLS_DIR "Modules" +$NUGET_EXE = Join-Path $TOOLS_DIR "nuget.exe" +$CAKE_EXE = Join-Path $TOOLS_DIR "Cake/Cake.exe" +$NUGET_URL = "https://dist.nuget.org/win-x86-commandline/latest/nuget.exe" +$PACKAGES_CONFIG = Join-Path $TOOLS_DIR "packages.config" +$PACKAGES_CONFIG_MD5 = Join-Path $TOOLS_DIR "packages.config.md5sum" +$ADDINS_PACKAGES_CONFIG = Join-Path $ADDINS_DIR "packages.config" +$MODULES_PACKAGES_CONFIG = Join-Path $MODULES_DIR "packages.config" + +# Should we use mono? +$UseMono = ""; +if($Mono.IsPresent) { + Write-Verbose -Message "Using the Mono based scripting engine." + $UseMono = "-mono" +} + +# Should we use the new Roslyn? +$UseExperimental = ""; +if($Experimental.IsPresent -and !($Mono.IsPresent)) { + Write-Verbose -Message "Using experimental version of Roslyn." + $UseExperimental = "-experimental" +} + +# Is this a dry run? +$UseDryRun = ""; +if($WhatIf.IsPresent) { + $UseDryRun = "-dryrun" +} + +# Make sure tools folder exists +if ((Test-Path $PSScriptRoot) -and !(Test-Path $TOOLS_DIR)) { + Write-Verbose -Message "Creating tools directory..." + New-Item -Path $TOOLS_DIR -Type directory | out-null +} + +# Make sure that packages.config exist. +if (!(Test-Path $PACKAGES_CONFIG)) { + Write-Verbose -Message "Downloading packages.config..." + try { (New-Object System.Net.WebClient).DownloadFile("http://cakebuild.net/download/bootstrapper/packages", $PACKAGES_CONFIG) } catch { + Throw "Could not download packages.config." + } +} + +# Try find NuGet.exe in path if not exists +if (!(Test-Path $NUGET_EXE)) { + Write-Verbose -Message "Trying to find nuget.exe in PATH..." + $existingPaths = $Env:Path -Split ';' | Where-Object { (![string]::IsNullOrEmpty($_)) -and (Test-Path $_ -PathType Container) } + $NUGET_EXE_IN_PATH = Get-ChildItem -Path $existingPaths -Filter "nuget.exe" | Select -First 1 + if ($NUGET_EXE_IN_PATH -ne $null -and (Test-Path $NUGET_EXE_IN_PATH.FullName)) { + Write-Verbose -Message "Found in PATH at $($NUGET_EXE_IN_PATH.FullName)." + $NUGET_EXE = $NUGET_EXE_IN_PATH.FullName + } +} + +# Try download NuGet.exe if not exists +if (!(Test-Path $NUGET_EXE)) { + Write-Verbose -Message "Downloading NuGet.exe..." + try { + (New-Object System.Net.WebClient).DownloadFile($NUGET_URL, $NUGET_EXE) + } catch { + Throw "Could not download NuGet.exe." + } +} + +# Save nuget.exe path to environment to be available to child processed +$ENV:NUGET_EXE = $NUGET_EXE + +# Restore tools from NuGet? +if(-Not $SkipToolPackageRestore.IsPresent) { + Push-Location + Set-Location $TOOLS_DIR + + # Check for changes in packages.config and remove installed tools if true. + [string] $md5Hash = MD5HashFile($PACKAGES_CONFIG) + if((!(Test-Path $PACKAGES_CONFIG_MD5)) -Or + ($md5Hash -ne (Get-Content $PACKAGES_CONFIG_MD5 ))) { + Write-Verbose -Message "Missing or changed package.config hash..." + Remove-Item * -Recurse -Exclude packages.config,nuget.exe + } + + Write-Verbose -Message "Restoring tools from NuGet..." + $NuGetOutput = Invoke-Expression "&`"$NUGET_EXE`" install -ExcludeVersion -OutputDirectory `"$TOOLS_DIR`"" + + if ($LASTEXITCODE -ne 0) { + Throw "An error occured while restoring NuGet tools." + } + else + { + $md5Hash | Out-File $PACKAGES_CONFIG_MD5 -Encoding "ASCII" + } + Write-Verbose -Message ($NuGetOutput | out-string) + + Pop-Location +} + +# Restore addins from NuGet +if (Test-Path $ADDINS_PACKAGES_CONFIG) { + Push-Location + Set-Location $ADDINS_DIR + + Write-Verbose -Message "Restoring addins from NuGet..." + $NuGetOutput = Invoke-Expression "&`"$NUGET_EXE`" install -ExcludeVersion -OutputDirectory `"$ADDINS_DIR`"" + + if ($LASTEXITCODE -ne 0) { + Throw "An error occured while restoring NuGet addins." + } + + Write-Verbose -Message ($NuGetOutput | out-string) + + Pop-Location +} + +# Restore modules from NuGet +if (Test-Path $MODULES_PACKAGES_CONFIG) { + Push-Location + Set-Location $MODULES_DIR + + Write-Verbose -Message "Restoring modules from NuGet..." + $NuGetOutput = Invoke-Expression "&`"$NUGET_EXE`" install -ExcludeVersion -OutputDirectory `"$MODULES_DIR`"" + + if ($LASTEXITCODE -ne 0) { + Throw "An error occured while restoring NuGet modules." + } + + Write-Verbose -Message ($NuGetOutput | out-string) + + Pop-Location +} + +# Make sure that Cake has been installed. +if (!(Test-Path $CAKE_EXE)) { + Throw "Could not find Cake.exe at $CAKE_EXE" +} + +# Start Cake +Write-Host "Running build script..." +Invoke-Expression "& `"$CAKE_EXE`" `"$Script`" -target=`"$Target`" -configuration=`"$Configuration`" -verbosity=`"$Verbosity`" $UseMono $UseDryRun $UseExperimental $ScriptArgs" +exit $LASTEXITCODE diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..72dffeb --- /dev/null +++ b/build.sh @@ -0,0 +1,131 @@ +#!/usr/bin/env bash + +########################################################################## +# This is the Cake bootstrapper script for Linux and OS X. +# This file was downloaded from https://github.com/cake-build/resources +# Feel free to change this file to fit your needs. +########################################################################## + +# Define directories. +SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd ) +TOOLS_DIR=$SCRIPT_DIR/tools +ADDINS_DIR=$TOOLS_DIR/Addins +MODULES_DIR=$TOOLS_DIR/Modules +NUGET_EXE=$TOOLS_DIR/nuget.exe +CAKE_EXE=$TOOLS_DIR/Cake/Cake.exe +PACKAGES_CONFIG=$TOOLS_DIR/packages.config +PACKAGES_CONFIG_MD5=$TOOLS_DIR/packages.config.md5sum +ADDINS_PACKAGES_CONFIG=$ADDINS_DIR/packages.config +MODULES_PACKAGES_CONFIG=$MODULES_DIR/packages.config + +# Define md5sum or md5 depending on Linux/OSX +MD5_EXE= +if [[ "$(uname -s)" == "Darwin" ]]; then + MD5_EXE="md5 -r" +else + MD5_EXE="md5sum" +fi + +# Define default arguments. +SCRIPT="build.cake" +TARGET="Default" +CONFIGURATION="Release" +VERBOSITY="verbose" +DRYRUN= +SHOW_VERSION=false +SCRIPT_ARGUMENTS=() + +# Parse arguments. +for i in "$@"; do + case $1 in + -s|--script) SCRIPT="$2"; shift ;; + -t|--target) TARGET="$2"; shift ;; + -c|--configuration) CONFIGURATION="$2"; shift ;; + -v|--verbosity) VERBOSITY="$2"; shift ;; + -d|--dryrun) DRYRUN="-dryrun" ;; + --version) SHOW_VERSION=true ;; + --) shift; SCRIPT_ARGUMENTS+=("$@"); break ;; + *) SCRIPT_ARGUMENTS+=("$1") ;; + esac + shift +done + +# Make sure the tools folder exist. +if [ ! -d "$TOOLS_DIR" ]; then + mkdir "$TOOLS_DIR" +fi + +# Make sure that packages.config exist. +if [ ! -f "$TOOLS_DIR/packages.config" ]; then + echo "Downloading packages.config..." + curl -Lsfo "$TOOLS_DIR/packages.config" http://cakebuild.net/download/bootstrapper/packages + if [ $? -ne 0 ]; then + echo "An error occured while downloading packages.config." + exit 1 + fi +fi + +# Download NuGet if it does not exist. +if [ ! -f "$NUGET_EXE" ]; then + echo "Downloading NuGet..." + curl -Lsfo "$NUGET_EXE" https://dist.nuget.org/win-x86-commandline/latest/nuget.exe + if [ $? -ne 0 ]; then + echo "An error occured while downloading nuget.exe." + exit 1 + fi +fi + +# Restore tools from NuGet. +pushd "$TOOLS_DIR" >/dev/null +if [ ! -f "$PACKAGES_CONFIG_MD5" ] || [ "$( cat "$PACKAGES_CONFIG_MD5" | sed 's/\r$//' )" != "$( $MD5_EXE "$PACKAGES_CONFIG" | awk '{ print $1 }' )" ]; then + find . -type d ! -name . | xargs rm -rf +fi + +mono "$NUGET_EXE" install -ExcludeVersion +if [ $? -ne 0 ]; then + echo "Could not restore NuGet tools." + exit 1 +fi + +$MD5_EXE "$PACKAGES_CONFIG" | awk '{ print $1 }' >| "$PACKAGES_CONFIG_MD5" + +popd >/dev/null + +# Restore addins from NuGet. +if [ -f "$ADDINS_PACKAGES_CONFIG" ]; then + pushd "$ADDINS_DIR" >/dev/null + + mono "$NUGET_EXE" install -ExcludeVersion + if [ $? -ne 0 ]; then + echo "Could not restore NuGet addins." + exit 1 + fi + + popd >/dev/null +fi + +# Restore modules from NuGet. +if [ -f "$MODULES_PACKAGES_CONFIG" ]; then + pushd "$MODULES_DIR" >/dev/null + + mono "$NUGET_EXE" install -ExcludeVersion + if [ $? -ne 0 ]; then + echo "Could not restore NuGet modules." + exit 1 + fi + + popd >/dev/null +fi + +# Make sure that Cake has been installed. +if [ ! -f "$CAKE_EXE" ]; then + echo "Could not find Cake.exe at '$CAKE_EXE'." + exit 1 +fi + +# Start Cake +if $SHOW_VERSION; then + exec mono "$CAKE_EXE" -version +else + exec mono "$CAKE_EXE" $SCRIPT -verbosity=$VERBOSITY -configuration=$CONFIGURATION -target=$TARGET $DRYRUN "${SCRIPT_ARGUMENTS[@]}" +fi \ No newline at end of file diff --git a/docfx/.gitignore b/docfx/.gitignore new file mode 100644 index 0000000..4378419 --- /dev/null +++ b/docfx/.gitignore @@ -0,0 +1,9 @@ +############### +# folder # +############### +/**/DROP/ +/**/TEMP/ +/**/packages/ +/**/bin/ +/**/obj/ +_site diff --git a/docfx/api/.gitignore b/docfx/api/.gitignore new file mode 100644 index 0000000..da7c71b --- /dev/null +++ b/docfx/api/.gitignore @@ -0,0 +1,4 @@ +############### +# temp file # +############### +*.yml diff --git a/docfx/api/index.md b/docfx/api/index.md new file mode 100644 index 0000000..c8cfa22 --- /dev/null +++ b/docfx/api/index.md @@ -0,0 +1,5 @@ +# API documentation + +Use the links on the left to navigate the addin's API. + +> Raise any issues [on GitHub](https://github.com/agc93/Cake.AzCopy), even against the documentation. \ No newline at end of file diff --git a/docfx/doc/contributing.md b/docfx/doc/contributing.md new file mode 100644 index 0000000..e85814f --- /dev/null +++ b/docfx/doc/contributing.md @@ -0,0 +1,21 @@ +# Contributing + +This is very much an active project so any and all contributions are welcome, even just finding issues! + +## Reporting issues + +All issues should be tracked on [GitHub](https://github.com/agc93/Cake.AzCopy), with enough information to reproduce the issue. + +## Code Contributions + +This repository is based around the Git Flow workflow, using feature branches and pull requests to manage incoming changes and fixes. Generally speaking you can follow the same guidance as Cake itself (found [here](http://cakebuild.net/docs/contributing/guidelines)), which can be summarised as follows: + +- Find a change or fix you want to implement +- Fork the repo +- Create a new branch named `feature/` and make your changes +- Open a PR from your feature branch against the `develop` branch (include the GitHub issue number for fixes) +- Success! I will provide feedback if needed, or just accept the changes directly and they should appear in the next release + +## License + +Note that this project (and all contributions) fall under the MIT License terms. \ No newline at end of file diff --git a/docfx/doc/intro.md b/docfx/doc/intro.md new file mode 100644 index 0000000..f07c58f --- /dev/null +++ b/docfx/doc/intro.md @@ -0,0 +1,50 @@ +# Getting Started + +## Install AzCopy + +First, you'll need to make sure you have AzCopy installed. You can find the full documentation of how to install AzCopy for Windows [here](https://docs.microsoft.com/en-us/azure/storage/storage-use-azcopy#download-and-install-azcopy) and AzCopy for Linux [here](https://docs.microsoft.com/en-us/azure/storage/storage-use-azcopy-linux#download-and-install-azcopy). + +Since this addin relies on the underlying AzCopy CLI to perform copy operations, it runs on either Linux or Windows + +> [!WARNING] +> Since AzCopy is not supported on macOS, this addin is also not supported for macOS. + +> [!INFO] +> For this addin to work, you need to make sure one of `AzCopy.exe` or `azcopy` is available in the PATH or the `tools/` folder. + +## Including the addin + +At the top of your script, just add the following to install the addin: + +``` +#addin nuget:?package=Cake.AzCopy +``` + +## Usage + +The addin exposes a single (overloaded) method alias `AzCopy` to use when for copy operations. + +To use the defaults, just run the `AzCopy(string, string)` alias: + +```csharp +AzCopy("https://myaccount.blob.core.windows.net/mycontainer/", "~/temp/"); +``` + +To use the fluent settings API, just run the `AzCopy(string, string, Action)` alias: + +```csharp +AzCopy("https://myaccount.blob.core.windows.net/mycontainer/", "~/temp/", settings => settings.UsePattern("*.txt")); +``` + +To use the object settings API, just run the `AzCopy(string, string, AzCopySettings)` alias: + +```csharp +var settings = new AzCopySettings { Pattern = "*.txt" }; +AzCopy("https://myaccount.blob.core.windows.net/mycontainer/", "~/temp/", settings); +``` + +The addin will take care of adapting the commands and options to the platform your build is running on. + +## Settings + +Full information on the various settings available is provided in the [Settings documentation](settings.md). \ No newline at end of file diff --git a/docfx/doc/packages.md b/docfx/doc/packages.md new file mode 100644 index 0000000..29df19b --- /dev/null +++ b/docfx/doc/packages.md @@ -0,0 +1,17 @@ +# Packages + +You can include the addin in your script with: + +```csharp +#addin nuget:?package=Cake.AzCopy + +//or to use the latest development release +#addin nuget:?package=Cake.AzCopy&prerelease +``` + +The NuGet prerelease packages are automatically built and deployed from the `develop` branch so they can be considered bleeding-edge while the non-prerelease packages will be much more stable. + +Versioning is predominantly SemVer-compliant so you can set your version constraints if you're worried about changes. + +> [!NOTE] +> These packages **do not** include AzCopy itself so you will need to have that available in your environment first. \ No newline at end of file diff --git a/docfx/doc/settings.md b/docfx/doc/settings.md new file mode 100644 index 0000000..7a00c5d --- /dev/null +++ b/docfx/doc/settings.md @@ -0,0 +1,48 @@ +# Settings + +This Cake addin supports the majority of the options supported by the AzCopy CLI. + +Note, however, that there are some options which are ignored when running on Linux due to the Linux version of AzCopy not supporting all functionality. + +This addin supports both a fluent settings API and an object-oriented API. + +What does this look like in practice? + +A full example of the fluent API: + +```csharp +AzCopy(source, destination, settings => + settings.UsePattern("*.txt") + .UseDestinationAccountKey(accountKey) // or UseDestinationSignature + .UseSourceAccountKey(accountKey) // or UseSourceSignature + .CopyRecursively() + .SetBlobType(BlobType.Block) + .EnableChecksums() + .LogToFile("./logfile") // ignored on Linux + .AddResponseFile("./parameters.txt") + .SetFileBehaviour(FileHandling.ExcludeNewer|FileHandling.UpdateLastModified) + .UseDelimiter(':') + .SetConcurrentOperationsCount(512) + .SetContentType("text/plain") +); +``` + +A full example of the object API: + +```csharp +var settings = new AzCopySettings { + Pattern = "*.txt", + DestinationKey = accountKey, // or DestinationSAS + SourceKey = sourceKey, // or SourceSAS + Recursive = true, + BlobType = BlobType.Block, + UseChecksum = true, + LogFile = "./logfile" // ignored on Linux + ParameterFiles = new List { "./parameters.txt" }, + FileHandlingBehaviour = FileHandling.ExcludeNewer|FileHandling.UpdateLastModified, + Delimiter = ':', + ConcurrentOperations = 512, + TargetContentType = "text/plain" +}; +AzCopy(source, destination, settings); +``` \ No newline at end of file diff --git a/docfx/doc/toc.yml b/docfx/doc/toc.yml new file mode 100644 index 0000000..78630a8 --- /dev/null +++ b/docfx/doc/toc.yml @@ -0,0 +1,8 @@ +- name: Introduction + href: intro.md +- name: Settings + href: settings.md +- name: Contributing + href: contributing.md +- name: NuGet Package + href: packages.md \ No newline at end of file diff --git a/docfx/docfx.json b/docfx/docfx.json new file mode 100644 index 0000000..1804e6b --- /dev/null +++ b/docfx/docfx.json @@ -0,0 +1,80 @@ +{ + "metadata": [ + { + "src": [ + { + "files": [ + "src/Cake.AzCopy/*.csproj" + ], + "exclude": [ + "**/obj/**", + "**/bin/**", + "docfx/**" + ], + "src": "../" + } + ], + "dest": "api", + "properties": { + "TargetFramework": "netstandard1.6" + } + } + ], + "build": { + "content": [ + { + "files": [ + "api/**.yml", + "api/index.md" + ] + }, + { + "files": [ + "doc/**.md", + "doc/**/toc.yml" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + }, + { + "files": [ + "toc.yml", + "*.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], + "resource": [ + { + "files": [ + "assets/**" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], + "overwrite": [ + { + "files": [ + "apidoc/**.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], + "dest": "_site", + "template": [ + "statictoc" + ], + "noLangKeyword": false + } +} \ No newline at end of file diff --git a/docfx/index.md b/docfx/index.md new file mode 100644 index 0000000..14f8cd0 --- /dev/null +++ b/docfx/index.md @@ -0,0 +1,10 @@ +# Cake.AzCopy + +A simple Cake addin powered by AzCopy for uploading and downloading to/from Azure Storage (including Blob, Table and Files). + +# Using this documentation: + +Click the tabs at the top of the page to navigate: + +- **Documentation**: General documentation +- **Reference**: Full API documentation diff --git a/docfx/toc.yml b/docfx/toc.yml new file mode 100644 index 0000000..cd02d24 --- /dev/null +++ b/docfx/toc.yml @@ -0,0 +1,6 @@ + +- name: Documentation + href: doc/ +- name: Reference + href: api/ + homepage: api/index.md diff --git a/helpers.cake b/helpers.cake new file mode 100644 index 0000000..0987467 --- /dev/null +++ b/helpers.cake @@ -0,0 +1,49 @@ +List GetContent(IEnumerable frameworks, ProjectCollection projects, string configuration, Func projectFilter = null) { + projectFilter = projectFilter ?? (p => true); + var content = new List(); + foreach (var framework in frameworks) { + foreach (var project in projects.SourceProjects.Where(projectFilter)) { + Verbose("Loading package files for " + project.Name); + var match = GetFiles(project.Path.GetDirectory() + "/bin/" + configuration + "/" + framework + "/" + project.Name +".*"); + var libFiles = match + .Where(f => f.GetExtension() != ".pdb") + .Select(f => new NuSpecContent { Source = f.FullPath, Target = "lib/net45"}); + content.AddRange(libFiles); + } + } + return content; +} + +public class ProjectCollection { + public IEnumerable SourceProjects {get;set;} + public IEnumerable SourceProjectPaths {get { return SourceProjects.Select(p => p.Path.GetDirectory()); } } + public IEnumerable TestProjects {get;set;} + public IEnumerable TestProjectPaths { get { return TestProjects.Select(p => p.Path.GetDirectory()); } } + public IEnumerable AllProjects { get { return SourceProjects.Concat(TestProjects); } } + public IEnumerable AllProjectPaths { get { return AllProjects.Select(p => p.Path.GetDirectory()); } } +} + +ProjectCollection GetProjects(FilePath slnPath, string configuration) { + var solution = ParseSolution(slnPath); + var projects = solution.Projects.Where(p => p.Type != "{2150E333-8FDC-42A3-9474-1A3956D46DE8}"); + var testAssemblies = projects.Where(p => p.Name.Contains(".Tests")).Select(p => p.Path.GetDirectory() + "/bin/" + configuration + "/" + p.Name + ".dll"); + return new ProjectCollection { + SourceProjects = projects.Where(p => !p.Name.Contains(".Tests")), + TestProjects = projects.Where(p => p.Name.Contains(".Tests")) + }; + +} + + +public string GetRuntimeBuild(string runtime) { + var commands = new Dictionary { + ["centos.7-x64"] = "-t rpm -d libunwind -d libicu", + ["fedora.25-x64"] = "-t rpm -d libunwind -d libicu", + ["ubuntu.14.04-x64"] = "-t deb -d libunwind8 -d libicu52", + ["ubuntu.16.04-x64"] = "-t deb -d libunwind8 -d libicu52", + ["debian.8-x64"] = "-t deb -d libunwind8 -d libicu52", + ["rhel.7-x64"] = "-t rpm -d libunwind -d libicu" + }; + var s = commands[runtime]; + return s; +} \ No newline at end of file diff --git a/src/Cake.AzCopy/AzCopySettingsExtensions.cs b/src/Cake.AzCopy/AzCopySettingsExtensions.cs index 76a350b..9060d9a 100644 --- a/src/Cake.AzCopy/AzCopySettingsExtensions.cs +++ b/src/Cake.AzCopy/AzCopySettingsExtensions.cs @@ -1,3 +1,5 @@ +using Cake.Core.IO; + namespace Cake.AzCopy { public static class AzCopySettingsExtensions @@ -19,6 +21,7 @@ public static class AzCopySettingsExtensions public static AzCopySettings UseDestinationSignature(this AzCopySettings settings, string sas) { settings.DestinationSAS = sas; + return settings; } public static AzCopySettings UseSourceSignature(this AzCopySettings settings, string sas) { @@ -68,7 +71,7 @@ public static class AzCopySettingsExtensions return settings; } - public static AzCopySettings SetConcurrentOperationCount(this AzCopySettings settings, int count) { + public static AzCopySettings SetConcurrentOperationsCount(this AzCopySettings settings, int count) { if (count <= 512) { settings.ConcurrentOperations = count; }