Make launch.json less confusing

[TwitchBronBron]

Our launch config options are confusing to newcomers, sometimes even to seasoned users of our extension. It's time for us to rethink the patterns in order to help everyone better use the tools.

Part of the confusion is around rootDir, sourceDirs, and the concept of a staging dir/outdir. in scenario 1, rootDir points to your code, and that's what should be deployed. But for scenario 2 and 3, rootDir is actually the "staging directory" for your build process, yet it's the start of the extension's process. It all gets very confusing. So, I have a proposal for simplifying and clarifying our configs. Here are the patterns:

Overall, i propose the following changes to launch.json:

• remove sourceDirs
• add sources and stagingDir

You won't be able to use rootDir and files at the same time as sources. Hopefully this can be enforced in json schema, but if not possible, it'll definitely be enforced at launch time and fail early.

I do not expect this to be a breaking change, as we should be able to support the old patterns and the new patterns at the same time, but we will see once I get into it.

1. Project with no custom build process

This is currently supported by our extension, an we're not making changes to this pattern. Continue using rootDir for the root of your project, and specify an array of files for what files should be included in the zip. In this situation, users should not specify a stagingDir so the extension knows it needs to copy to staging. If you specify a stagingDir, it is assumed that you're copying the files there yourself...so don't use it in this scenario.

{
    "type": "brightscript",
    "rootDir": "${workspaceFolder}",
    "files": [
        "manifest",
        "source/**/*.*",
        "components/**/*.*",
        "images/**/*.*"
    ]
}

2. custom copy-and-paste build process.

This requires that line numbers and project-relative paths remain unchanged.
We currently support this concept, but it's confusing. You need to use sourceDirs to point to source folders, and rootDir points to the OUTPUT folder. Instead, we should have a different pattern for this.

The changes:

• deprecate sourceDirs since "dirs" doesn't accurately describe its contents anymore
• introduce new sources property to specify paths to source code
  • this is NOT used to copy files: it only serves to translate breakpoints from source to dest, and translate device locations back to source
  • supports relative or absolute paths to roku-structured folders (i.e. containing /source and /components and /manifest files)
  • supports {src;dest} objects that allow mapping source folders to differently-named dest folders
• introduce new stagingDir property which is where the engineer will write out their generated code. This is a required property.
  • CHANGE: the extension will not copy this folder contents to .roku-deploy-staging. Instead, the extension will use this existing staging folder to inject breakpoints and rewrite sourcemaps. This should provide some performance improvements by eliminating a second staging step.

Example scenario 1
The "build" prelaunch task copies the src folder to dist and then replaces values in dist/source/config.brs with environment-specific values.

{
    "type": "brightscript",
    "preLaunchTask": "build",
    "sources": [
        "${workspaceFolder}/src"
    ],
    //required when using `sources`. Your build system moves the files here.
    "stagingDir": "${workspaceFolder}/dist",
}

Example scenario 2
The "build" prelaunch task merges "Base" and "Flavor1" projects into the "dist" folder, copies the "swrve-roku-sdk" folder into "components/SwrveComponents", and renames runners/main-dev.brs to source/main.brs.

{
    "type": "brightscript",
    "preLaunchTask": "build",
    "sources": [
        "${workspaceFolder}/Base",
        "${workspaceFolder}/Flavor1",
        { "src": "${workspaceFolder}/swrve-roku-sdk/SwrveComponents", "dest": "${stagingDir}/components/SwrveComponents" },
        { "src": "${workspaceFolder}/runners/main-dev.brs", "dest": "source/main.brs" }
    ],
    //required when using `sources`. Your build system moves the files here.
    "stagingDir": "${workspaceFolder}/dist",
},

3. sourcemap-enabled custom build (i.e. BrighterScript)

In this scenario, the tool generates sourcemaps for every transformation, which means we can use sourcemaps to translate source files to staging, and then also staging locations back to source locations. Since sourcemaps are generated, "sources" should be omitted as the sourcemaps will be used exclusively.

{
    "type": "brightscript",
    //this command can be whatever you want. just make sure it generates sourcemaps
    "preLaunchTask": "Compile BrighterScript Code",
    //brighterscript writes files to "dist"
    "stagingDir": "${workspace folder}/dist"
}