Add documentation about RootDirectory (#15617)

* Add documentation about RootDirectory

* Review feedback

* Add csharp and typescript examples

* Use dotnet 8

* Use latest pulumi version

Author: Frassle

.github/workflows/scheduled-test.yml

@@ -81,6 +81,8 @@ jobs:
 
       - name: Install Pulumi
         uses: pulumi/actions@v4
+        with:
+          pulumi-version: latest
 
       - name: Check out the code
         uses: actions/checkout@v3

content/docs/iac/concepts/projects/_index.md

@@ -104,6 +104,14 @@ When your Pulumi program refers to resources in the local filesystem, paths are
 
 {{< example-program path="awsx-ecr-image" >}}
 
+## Root-relative paths
+
+You can get the directory containing the `Pulumi.yaml` file, which may differ from your working directory if it specified a `main` option (see [main attribute](/docs/reference/pulumi-yaml/#attributes)), with the `ProjectDirectory` function.
+
+The path returned is an absolute path. When using this in resource properties, ensure it's relative to the working directory. This prevents diffs from running the project on multiple machines with different roots.
+
+{{< example-program path="awsx-root-directory" >}}
+
 ## Getting the current project programmatically
 
 The {{< pulumi-getproject >}} function returns the name of the currently deploying project. This can be useful for naming or tagging resources.
@@ -166,8 +174,7 @@ variables:
 ## Stack settings files {#stack-settings-file}
 
 Each stack that is created in a project will have a file named `Pulumi.<stackname>.yaml` that contains the configuration specific to this stack. This file typically resides in the root of the project directory.
-To change the location where stack configuration files are stored for a given project, set the `stackConfigDir` metadata attribute to a relative directory.
 
 For stacks that are actively developed by multiple members of a team, the recommended practice is to check them into source control as a means of collaboration. Since secret values are encrypted, it is safe to check in these stack settings. When using ephemeral stacks, the stack settings are typically not checked into source control.
 
-For detailed information about the structure and format of stack settings files, see the [Stack settings file reference](/docs/iac/concepts/projects/stack-settings-file/). For more information about configuration and how to manage these files on the command line and programmatically, refer to the [Configuration](/docs/concepts/config/) and [Secrets](/docs/concepts/secrets/) documentation.
+For more information about configuration and how to manage these files on the command line and programmatically, refer to the [Configuration](/docs/concepts/config/) and [Secrets](/docs/concepts/secrets/) documentation.

static/programs/awsx-root-directory-csharp/Program.cs

@@ -0,0 +1,29 @@
+using System.Collections.Generic;
+using System.IO;
+using Pulumi;
+using Awsx = Pulumi.Awsx;
+
+return await Deployment.RunAsync(() =>
+{
+    var root = Pulumi.Deployment.Instance.RootDirectory;
+    var cwd = Directory.GetCurrentDirectory();
+    var appPath = Path.Combine(root, "app");
+    var relativePath = Path.GetRelativePath(cwd, appPath);
+
+    var repository = new Awsx.Ecr.Repository("repository", new()
+    {
+        ForceDelete = true,
+    });
+
+    var image = new Awsx.Ecr.Image("image", new()
+    {
+        RepositoryUrl = repository.Url,
+        Context = relativePath,
+        Platform = "linux/amd64",
+    });
+
+    return new Dictionary<string, object?>
+    {
+        ["url"] = repository.Url,
+    };
+});

static/programs/awsx-root-directory-csharp/Pulumi.yaml

@@ -0,0 +1,3 @@
+name: awsx-root-directory-csharp
+runtime:
+  name: dotnet

static/programs/awsx-root-directory-csharp/app/Dockerfile

@@ -0,0 +1 @@
+FROM nginx

static/programs/awsx-root-directory-csharp/awsx-root-directory-csharp.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Pulumi" Version="[3.87, 4.0.0)" />
+    <PackageReference Include="Pulumi.Aws" Version="6.*" />
+    <PackageReference Include="Pulumi.Awsx" Version="2.*" />
+  </ItemGroup>
+
+</Project>

static/programs/awsx-root-directory-go/Pulumi.yaml

@@ -0,0 +1,2 @@
+name: awsx-root-directory-go
+runtime: go

static/programs/awsx-root-directory-go/app/Dockerfile

@@ -0,0 +1 @@
+FROM nginx

static/programs/awsx-root-directory-go/go.mod

@@ -0,0 +1,8 @@
+module awsx-root-directory-go
+
+go 1.23.11
+
+require (
+	github.com/pulumi/pulumi-awsx/sdk/v2 v2.13.0
+	github.com/pulumi/pulumi/sdk/v3 v3.153.0
+)

static/programs/awsx-root-directory-go/main.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/pulumi/pulumi-awsx/sdk/v2/go/awsx/ecr"
+	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
+)
+
+func main() {
+	pulumi.Run(func(ctx *pulumi.Context) error {
+		root := ctx.RootDirectory()
+		cwd, err := os.Getwd()
+		if err != nil {
+			return err
+		}
+		path := filepath.Join(root, "app")
+		path, err = filepath.Rel(cwd, path)
+		if err != nil {
+			return err
+		}
+
+		repository, err := ecr.NewRepository(ctx, "repository", &ecr.RepositoryArgs{
+			ForceDelete: pulumi.Bool(true),
+		})
+		if err != nil {
+			return err
+		}
+
+		_, err = ecr.NewImage(ctx, "image", &ecr.ImageArgs{
+			RepositoryUrl: repository.Url,
+			Context:       pulumi.String(path),
+			Platform:      pulumi.String("linux/amd64"),
+		})
+		if err != nil {
+			return err
+		}
+
+		ctx.Export("url", repository.Url)
+		return nil
+	})
+}