Documentation changes for new tools modifications for ARMC5/ARMC6 usage #1024

SenRamakri · 2019-03-21T20:32:17Z

DO NOT MERGE *
This is documentation to go with new tools changes being implemented for supporting
ARMC5 with mbed-os tools.

This change depends on tools changes being implemented by @bridadan which are yet to be
landed in PR form. But please start the review process for this documentation change so that we are ready to go when tools changes are merged.

Tagging: @bridadan @bulislaw @AnotherButler @iriark01 @screamerbg @ChiefBureaucraticOfficer @kegilbert

bridadan

Already looking quite good, a few suggestions:

bridadan · 2019-03-21T21:00:55Z

docs/reference/configuration/mbed_targets.md

-<span class="notes">**Note:** Although you can specify `ARMC5` in `supported_toolchains` in `targets.json`, it's not a valid option for `--toolchain` when compiling using [Mbed CLI](../tools/developing-mbed-cli.html). Arm Compiler 6 is the default Arm toolchain for Mbed OS development. Most Mbed OS platforms are already compatible with Arm Compiler 6. Some existing targets still supporting Arm Compiler 5 will be migrated to Arm Compiler 6 in the future. Please be aware that you must use Arm Compiler 6 for future development, and we will validate all code contributions to Mbed OS Arm Compiler 6.
-</span>
+* If a target specify `ARM` in `supported_toolchains`, it means the target supports compiling with both `Arm Compiler 5` and `Arm Compiler 6`. Note that starting with `MbedOS 5.12 release`, `Arm Compiler 6` will 
+be the default ARM Compiler for MbedOS. So, for a target which specifies `ARM` in `supported_toolchains`, the system will default to using `Arm Compiler 6` when you specify `-t ARM` with `mbed compile` command. If the build system


Missing a space here:

Suggested change

be the default ARM Compiler for MbedOS. So, for a target which specifies `ARM` in `supported_toolchains`, the system will default to using `Arm Compiler 6` when you specify `-t ARM` with `mbed compile` command. If the build system

be the default ARM Compiler for Mbed OS. So, for a target which specifies `ARM` in `supported_toolchains`, the system will default to using `Arm Compiler 6` when you specify `-t ARM` with `mbed compile` command. If the build system

docs/tools/tools_intro.md

bridadan · 2019-03-21T21:02:24Z

docs/reference/configuration/mbed_targets.md

+be the default ARM Compiler for MbedOS. So, for a target which specifies `ARM` in `supported_toolchains`, the system will default to using `Arm Compiler 6` when you specify `-t ARM` with `mbed compile` command. If the build system
+fails to detect a valid configuration for `Arm Compiler 6`, it will automatically(without any manual intervention) try to detect if a valid confguration for `ARM Compiler 5` exists, and will continue using `ARM Compiler 5` if it successfully detects `ARM Compiler 5`. You may see a warning message in your standard output from build system indicating this behavior. 
+
+* You can only specify one of `ARM`, `ARMC5` or `ARMC6` for `supported_toolchains` for a target in `targets/targets.json` or `custom_targets.json`.


Good to know, I'm not currently erroring on this 😄. I can make this change.

bridadan · 2019-03-21T21:04:04Z

docs/reference/configuration/mbed_targets.md

-</span>
+* If a target specify `ARM` in `supported_toolchains`, it means the target supports compiling with both `Arm Compiler 5` and `Arm Compiler 6`. Note that starting with `MbedOS 5.12 release`, `Arm Compiler 6` will 
+be the default ARM Compiler for MbedOS. So, for a target which specifies `ARM` in `supported_toolchains`, the system will default to using `Arm Compiler 6` when you specify `-t ARM` with `mbed compile` command. If the build system
+fails to detect a valid configuration for `Arm Compiler 6`, it will automatically(without any manual intervention) try to detect if a valid confguration for `ARM Compiler 5` exists, and will continue using `ARM Compiler 5` if it successfully detects `ARM Compiler 5`. You may see a warning message in your standard output from build system indicating this behavior. 


I suggest being more definite when documenting the behavior of the tools:

Suggested change

fails to detect a valid configuration for `Arm Compiler 6`, it will automatically(without any manual intervention) try to detect if a valid confguration for `ARM Compiler 5` exists, and will continue using `ARM Compiler 5` if it successfully detects `ARM Compiler 5`. You may see a warning message in your standard output from build system indicating this behavior.

fails to detect a valid configuration for `Arm Compiler 6`, it will automatically(without any manual intervention) try to detect if a valid configuration for `ARM Compiler 5` exists, and will continue using `ARM Compiler 5` if it successfully detects `ARM Compiler 5`. You will see a warning message in your standard output from the build system indicating this behavior.

AnotherButler · 2019-03-21T21:10:22Z

docs/reference/configuration/mbed_targets.md


-If a target lists both `ARMC5` and `ARM` (or `ARMC6`) in `supported_toolchains`, the Arm Compiler 6.11 will be used when compiling with `ARM` option for `--toolchain`.
+- If you specify `ARMC5` in `supported_toolchains`, it means the target supports Arm Compiler 5 (version 5.06 update 6) only, and the build system uses Arm Compiler 5 when you specify `-t ARM` or `-t ARMC5` with `mbed compile` command. 


If the target supports Arm Compiler 5, will supported_toolchains show ARMC5, or do you have to manually add that?

@AnotherButler - Good question, the changes which Brian is working on will add everything as required and according to these rules. So no manual addition required from user or the reader of this documentation. But I said "If you specify" because this document is talking about "Adding and configuring targets".

So if I changed it to "If the target supports Arm Compiler 5 (version 5.06 update 6) only, supported_toolchains will specify ARMC5", would that be correct?

@AnotherButler - It is technically correct. But I think the intended audience for this document is someone who is adding or configuring a target, as in the document title. That's why its written as "if you specify.." meaning whoever is adding or configuring a target. But I also want that information to be available for anyone, so I created a link from cli-compile.md to here. So, Ill leave that up to you and if the new format is cleaner/compact I would keep that.

bridadan

Edits looking real nice!

bridadan · 2019-03-22T04:10:09Z

What would the URL for this doc be once it goes live? I will need to add this link to my tools PR. Thanks!

bridadan · 2019-03-22T04:12:26Z

Also, do we have docs telling the user how to upgrade to ARMC6? Should that be part of this doc or in a separate place?

iriark01 · 2019-03-22T05:41:07Z

What would the URL for this doc be once it goes live? I will need to add this link to my tools PR. Thanks!

https://os.mbed.com/docs/mbed-os/v5.12/reference/configuration.html
https://os.mbed.com/docs/mbed-os/v5.12/tools/compile.html
https://os.mbed.com/docs/mbed-os/v5.12/tools/index.html

docs/reference/configuration/mbed_targets.md

docs/tools/tools_intro.md

docs/reference/configuration/mbed_targets.md

docs/tools/tools_intro.md

SenRamakri · 2019-03-22T13:03:11Z

@iriark01 - I have pushed your suggestions, please take a look.

iriark01 · 2019-03-22T13:05:27Z

docs/tools/tools_intro.md

@@ -43,38 +43,11 @@ The Mbed Online Compiler is our in-house IDE and should be familiar to anyone wh
 | Arm v7A       | `Arm Compiler 6.11` |
 | Arm v8M       | `Arm Compiler 6.11` |

-For more information, please see the [Online Compiler page](developing-mbed-online-compiler.html).
+<span class="notes">**Note**: Arm Compiler 6 is the default Arm Compiler version for Mbed OS development, and is [free for use with Mbed OS]((https://os.mbed.com/docs/mbed-os/development/tools/index.html#compiler-versions). Most platforms are already compatible with it; platforms still supporting Arm Compiler 5 will be migrated to Arm Compiler 6. Please do not use Arm Compiler 5 in any new development, as its support will be deprecated in September 2019.


My mistake, in both notes, there are two (( in the link; there should be only one

iriark01 · 2019-03-22T13:05:31Z

docs/reference/configuration/mbed_targets.md

+
+- It's invalid to use `-t ARMC5` with the `mbed compile` command for a target that specifies `ARMC6` for `supported_toolchains`, and it's invalid to use `-t ARMC6` if `supported_toolchains` specifies `ARMC5`.
+
+<span class="notes">**Note**: Arm Compiler 6 is the default Arm Compiler version for Mbed OS development, and is [free for use with Mbed OS]((https://os.mbed.com/docs/mbed-os/development/tools/index.html#compiler-versions). Most platforms are already compatible with it; platforms still supporting Arm Compiler 5 will be migrated to Arm Compiler 6. Please do not use Arm Compiler 5 in any new development, as its support will be deprecated in September 2019.


My mistake, in both notes, there are two (( in the link; there should be only one

iriark01 · 2019-03-22T13:09:04Z

Tried to resolve the conflict but I don't know which version is actually correct. @SenRamakri please can you resolve those? And @bulislaw can you recheck and approve?

Fix note formatting, and add specific date at request of Product.

Make initial edits on PR.

Clarify note based on responses in comments.

Co-Authored-By: SenRamakri <[email protected]>

SenRamakri · 2019-03-22T13:21:18Z

@iremic - I have resolved the merge conflicts as well. Thanks much for making those changes.

iriark01 · 2019-03-22T13:22:55Z

Okay; I'll give Bartek time to dismiss his review or ask for more changes. Other than that we're good to go (I can fix the funky links when it's merged)

bulislaw

Looks good. One thing about page we are linking to tell users about free armc6 and how to get/confiugre it https://os.mbed.com/docs/mbed-os/development/tools/index.html#compiler-versions there's nothing there about free armc6 for mbed studio and how to use it with mbed cli.

iriark01 · 2019-03-22T13:36:40Z

Do we have that content anywhere? Do we need to write it?
(Full Mbed Studio docs here: https://os.mbed.com/docs/mbed-studio/)

iriark01 · 2019-03-22T14:09:19Z

Amanda said we have content in the release note; I'll see if I can get anything sensible into the docs from that

iriark01 · 2019-03-22T14:19:06Z

I'm merging this so we can see everything in one place (this is a fork, not a branch, so we don't get a preview on the docs site)

AnotherButler requested review from bridadan, bulislaw, screamerbg and a user March 21, 2019 20:37

SenRamakri requested review from theotherjimmy and kegilbert March 21, 2019 20:40

bridadan suggested changes Mar 21, 2019

View reviewed changes

AnotherButler reviewed Mar 21, 2019

View reviewed changes

kegilbert approved these changes Mar 21, 2019

View reviewed changes

bridadan approved these changes Mar 22, 2019

View reviewed changes

bridadan mentioned this pull request Mar 22, 2019

Fallback to ARMC5 when ARMC6 is not configured ARMmbed/mbed-os#10193

Merged

1 task

0xc0170 approved these changes Mar 22, 2019

View reviewed changes

bulislaw requested changes Mar 22, 2019

View reviewed changes

docs/reference/configuration/mbed_targets.md Outdated Show resolved Hide resolved

docs/tools/tools_intro.md Outdated Show resolved Hide resolved

iriark01 reviewed Mar 22, 2019

View reviewed changes

docs/reference/configuration/mbed_targets.md Outdated Show resolved Hide resolved

iriark01 reviewed Mar 22, 2019

View reviewed changes

docs/tools/tools_intro.md Outdated Show resolved Hide resolved

iriark01 reviewed Mar 22, 2019

View reviewed changes

SenRamakri and others added 7 commits March 22, 2019 08:18

Documentation changes for new tools modficiations for ARMC5/ARMC6 usage

ffbe7ec

Update note in tools_intro.md

a540c96

Fix note formatting, and add specific date at request of Product.

Changes to CLI compile documentation

c2d89fd

Edit mbed_targets.md

3ae82c1

Make initial edits on PR.

Clarify note in mbed_targets.md

b697950

Clarify note based on responses in comments.

Update docs/reference/configuration/mbed_targets.md

41c8634

Co-Authored-By: SenRamakri <[email protected]>

Update docs/tools/tools_intro.md

176fd2c

Co-Authored-By: SenRamakri <[email protected]>

SenRamakri force-pushed the sen_ToolchainDocsUpdate branch from 1198d04 to 176fd2c Compare March 22, 2019 13:20

bulislaw approved these changes Mar 22, 2019

View reviewed changes

iriark01 merged commit 0208b66 into ARMmbed:development Mar 22, 2019

	be the default ARM Compiler for MbedOS. So, for a target which specifies `ARM` in `supported_toolchains`, the system will default to using `Arm Compiler 6` when you specify `-t ARM` with `mbed compile` command. If the build system
	be the default ARM Compiler for Mbed OS. So, for a target which specifies `ARM` in `supported_toolchains`, the system will default to using `Arm Compiler 6` when you specify `-t ARM` with `mbed compile` command. If the build system

	fails to detect a valid configuration for `Arm Compiler 6`, it will automatically(without any manual intervention) try to detect if a valid confguration for `ARM Compiler 5` exists, and will continue using `ARM Compiler 5` if it successfully detects `ARM Compiler 5`. You may see a warning message in your standard output from build system indicating this behavior.
	fails to detect a valid configuration for `Arm Compiler 6`, it will automatically(without any manual intervention) try to detect if a valid configuration for `ARM Compiler 5` exists, and will continue using `ARM Compiler 5` if it successfully detects `ARM Compiler 5`. You will see a warning message in your standard output from the build system indicating this behavior.


		If a target lists both `ARMC5` and `ARM` (or `ARMC6`) in `supported_toolchains`, the Arm Compiler 6.11 will be used when compiling with `ARM` option for `--toolchain`.
		- If you specify `ARMC5` in `supported_toolchains`, it means the target supports Arm Compiler 5 (version 5.06 update 6) only, and the build system uses Arm Compiler 5 when you specify `-t ARM` or `-t ARMC5` with `mbed compile` command.


		- It's invalid to use `-t ARMC5` with the `mbed compile` command for a target that specifies `ARMC6` for `supported_toolchains`, and it's invalid to use `-t ARMC6` if `supported_toolchains` specifies `ARMC5`.

		<span class="notes">Note: Arm Compiler 6 is the default Arm Compiler version for Mbed OS development, and is [free for use with Mbed OS]((https://os.mbed.com/docs/mbed-os/development/tools/index.html#compiler-versions). Most platforms are already compatible with it; platforms still supporting Arm Compiler 5 will be migrated to Arm Compiler 6. Please do not use Arm Compiler 5 in any new development, as its support will be deprecated in September 2019.

Documentation changes for new tools modifications for ARMC5/ARMC6 usage #1024

Documentation changes for new tools modifications for ARMC5/ARMC6 usage #1024

Uh oh!

Conversation

SenRamakri commented Mar 21, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bridadan left a comment

Choose a reason for hiding this comment

Uh oh!

bridadan Mar 21, 2019

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bridadan Mar 21, 2019

Choose a reason for hiding this comment

Uh oh!

bridadan Mar 21, 2019

Choose a reason for hiding this comment

Uh oh!

AnotherButler Mar 21, 2019

Choose a reason for hiding this comment

Uh oh!

SenRamakri Mar 21, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler Mar 21, 2019

Choose a reason for hiding this comment

Uh oh!

SenRamakri Mar 21, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bridadan left a comment

Choose a reason for hiding this comment

Uh oh!

bridadan commented Mar 22, 2019

Uh oh!

bridadan commented Mar 22, 2019

Uh oh!

iriark01 commented Mar 22, 2019

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SenRamakri commented Mar 22, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iriark01 Mar 22, 2019

Choose a reason for hiding this comment

Uh oh!

iriark01 Mar 22, 2019

Choose a reason for hiding this comment

Uh oh!

iriark01 commented Mar 22, 2019

Uh oh!

SenRamakri commented Mar 22, 2019

Uh oh!

iriark01 commented Mar 22, 2019

Uh oh!

bulislaw left a comment

Choose a reason for hiding this comment

Uh oh!

iriark01 commented Mar 22, 2019

Uh oh!

iriark01 commented Mar 22, 2019

Uh oh!

iriark01 commented Mar 22, 2019

Uh oh!

Uh oh!

SenRamakri commented Mar 21, 2019 •

edited

Loading

SenRamakri Mar 21, 2019 •

edited

Loading

SenRamakri Mar 21, 2019 •

edited

Loading

SenRamakri commented Mar 22, 2019 •

edited

Loading