Document local build process

[xobs]

As per #5286, cloud building is not the preferred method for doing C++ development. However, the documentation does not reflect this anywhere.

For example, documentation for the pxt command only mentions the --cloud command, and indicates that this forces builds to happen "in the cloud". This implies that the default is to not do that.

Indeed, projects (such as https://github.com/microsoft/pxt-chibitronics#setup) indicate that a local toolchain is required to build, and other projects mention the invalid -yt flag (https://github.com/Microsoft/pxt-calliope#running).

There are a few issues here:

1. The --localbuild flag should be documented
2. It should be mentioned that --cloud is default and implied
3. Nonexistent flags such as -yt should be removed from documentation
4. It should be mentioned that, when doing C++ development, a local build environment is preferred.

[abchatra]

@darzu can you take a look at this issue?

[darzu]

@pelikhan , @mmoskal , could I get some help understanding what the right steps for local building are?

What's the right sequence of commands to run? What are the prerequisites? Can you confirm any of the assumptions on my documentation cleanup ToDo list below?

I've also had trouble getting local cpp builds working in the past, although today pxt serve --local seems to do everything I need. I can edit a .cpp file, see the rebuild, see the update in pxt-microbit.

[darzu]

ToDo:

• remove "--cloud" because I think it's the default (need to confirm)
• standardize documentation to mention "--local" for local builds, and remove mention of "--localbuild" because I think these are aliases (need to confirm)
• remove "-yt" from documentation
• move all local building documentation into pxt so it isn't duplicated between every target. This assumes different targets don't need different steps, need to confirm this
• explain that "--local" should be used when doing C++ development

[abchatra]

Different targets have different building instructions. For example minecraft. I prefer keeping them in the target even if they are duplicates.

[mmoskal]

I would much rather have something like: "If target has no C++ skip these steps." and then possibly minecraft have something like "Follow usual instructions at pxt-core and then XYZ". This will be way easier to maintain...

[pelikhan]

The CLI arguments have changed over time. The docs should be in "common-docs" so that they get versioned properly -- and you don't end up with newer flags for an older pxt version.

[darzu]

The CLI arguments have changed over time. The docs should be in "common-docs" so that they get versioned properly -- and you don't end up with newer flags for an older pxt version.

How would that work? Should the target readme.md reference a specific version of doc in common-docs?

[mmoskal]

The readme could just be very short and link to say https://arcade.makecode.com/building

[mmoskal]

(we have quite involved procedure for generating docs in editors, they derive from the base docs in pxt-core and pxt-common-packages and can override sections)