Document local build process

microsoft / pxt

Microsoft MakeCode (PXT - Programming eXperience Toolkit)

https://makecode.com

MIT License

2.1k stars 584 forks source link

Document local build process #5319

Open xobs opened 5 years ago

xobs commented 5 years ago

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:

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

abchatra commented 5 years ago

@darzu can you take a look at this issue?

darzu commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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

mmoskal commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

mmoskal commented 5 years ago

(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)