[edk2-devel] [PATCH edk2-CCodingStandardsSpecification v2 0/1] Prefer use of `static` C keyword over EDK2 type `STATIC`

[edk2-devel] [PATCH edk2-CCodingStandardsSpecification v2 0/1] Prefer use of `static` C keyword over EDK2 type `STATIC`

[Rebecca Cran]

Prefer use of `static` C keyword over EDK2 type `STATIC`

A while ago a decision was made on the edk2-devel mailing list that
the `STATIC` EDK2 type should be replaced with the C keyword `static`.

Following further discussion, it was decided to disallow static local
variables to prevent breakage when using GoogleTest.

Update the Coding Specification to match. While here, remove the
outdated section disallowing static functions since they're no longer
a problem.

Bump the revision to 2.4.

Changes from v1 to v2:
  Drop the change to the draft status.
  Add a sentence about static local variables not being allowed.

Rebecca Cran (1):
  Prefer use of `static` C keyword over EDK2 type `STATIC`

 5_source_files/54_code_file_structure.md    | 9 ++-------
 5_source_files/56_declarations_and_types.md | 2 +-
 README.md                                   | 3 ++-
 book.json                                   | 2 +-
 4 files changed, 6 insertions(+), 10 deletions(-)

-- 
2.48.1



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#121066): https://edk2.groups.io/g/devel/message/121066
Mute This Topic: https://groups.io/mt/110968938/7686176
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io]
-=-=-=-=-=-=-=-=-=-=-=-

[edk2-devel] [PATCH edk2-CCodingStandardsSpecification v2 1/1] Prefer use of `static` C keyword over EDK2 type `STATIC`

[Rebecca Cran]

A while ago a decision was made on the edk2-devel mailing list that
the `STATIC` EDK2 type should be replaced with the C keyword `static`.
Following further discussion, it was decided to disallow static local
variables to prevent breakage when using GoogleTest.

Update the Coding Specification to match. While here, remove the
outdated section disallowing static functions since they're no longer
a problem.

Bump the revision to 2.4.

Signed-off-by: Rebecca Cran <rebecca@bsdio.com>
---
 5_source_files/54_code_file_structure.md    | 9 ++-------
 5_source_files/56_declarations_and_types.md | 2 +-
 README.md                                   | 3 ++-
 book.json                                   | 2 +-
 4 files changed, 6 insertions(+), 10 deletions(-)

diff --git a/5_source_files/54_code_file_structure.md b/5_source_files/54_code_file_structure.md
index 0c4d6a26820c..c286b273fe42 100644
--- a/5_source_files/54_code_file_structure.md
+++ b/5_source_files/54_code_file_structure.md
@@ -269,7 +269,8 @@ other than at the top level of a file as specified by this document.
 
 #### 5.4.2.2 Static
 
-An object declared `STATIC` has either file or block scope.
+An object declared `static` has file scope.
+Objects may not be declared 'static' within functions.
 
 ##### 5.4.2.2.1 Do not reuse an object or function identifier with static storage duration.
 
@@ -277,9 +278,3 @@ Throughout the set of source files defined within a single .inf file, do not
 reuse an identifier with static storage duration. The compiler may not be
 confused by this, but the user may confuse unrelated variables with the same
 name.
-
-##### 5.4.2.2.2 Functions should not be declared STATIC.
-
-Some source-level debuggers are unable to resolve static functions. Until it
-can be verified that no one is dependent upon a debugger with this limitation,
-it is strongly recommended that functions not be declared static.
diff --git a/5_source_files/56_declarations_and_types.md b/5_source_files/56_declarations_and_types.md
index ec1803d980e1..77e3ce99c457 100644
--- a/5_source_files/56_declarations_and_types.md
+++ b/5_source_files/56_declarations_and_types.md
@@ -38,7 +38,7 @@
 Any abstract type that is defined must be constructed from other abstract types
 or from common EFI data types.
 
-#### 5.6.1.2 The use of int, unsigned, char, void, static, long is a violation of the coding convention.
+#### 5.6.1.2 The use of int, unsigned, char, void, long is a violation of the coding convention.
 
 The corresponding EFI types must be used instead.
 
diff --git a/README.md b/README.md
index 77cfdc8906b1..a8da462c3c46 100644
--- a/README.md
+++ b/README.md
@@ -114,4 +114,5 @@ Copyright (c) 2006-2017, Intel Corporation. All rights reserved.
 |          | [#425](https://bugzilla.tianocore.org/show_bug.cgi?id=425) [CCS] clarify line breaking and indentation requirements for multi-line function calls |            |
 |          | [#1656](https://bugzilla.tianocore.org/show_bug.cgi?id=1656) Update all Wiki pages for the BSD+Patent license change with SPDX identifiers        |            |
 |          | [#607](https://bugzilla.tianocore.org/show_bug.cgi?id=607) Document code comment requirements for spurious variable assignments                   |            |
-| 2.3      | Add 4.2 Directory names section and update File names section for the guidelines of module directory and file naming|September 2022||
+| 2.3      | Add 4.2 Directory names section and update File names section for the guidelines of module directory and file naming                              |September 2022|
+| 2.4      | The use of the 'static' C keyword is now preferred over the EDK2 type 'STATIC'                                                                    |February 2025|
diff --git a/book.json b/book.json
index d112b26e3ebf..a46c487e1b5c 100644
--- a/book.json
+++ b/book.json
@@ -2,7 +2,7 @@
   "variables" : {
     "draft"   : "yes",
     "title"   : "EDK II C Coding Standards Specification",
-    "version" : "Revision 2.2"
+    "version" : "Revision 2.4"
   },
   "plugins": ["puml-aleung"],
   "pluginsConfig": {}
-- 
2.48.1



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#121067): https://edk2.groups.io/g/devel/message/121067
Mute This Topic: https://groups.io/mt/110968939/7686176
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io]
-=-=-=-=-=-=-=-=-=-=-=-

Re: [edk2-devel] [PATCH edk2-CCodingStandardsSpecification v2 1/1] Prefer use of `static` C keyword over EDK2 type `STATIC`

[Michael D Kinney via groups.io]

Hi Rebecca,

The content changes look good.  2 comments below.

Mike

> -----Original Message-----
> From: Rebecca Cran <rebecca@bsdio.com>
> Sent: Monday, February 3, 2025 3:26 AM
> To: devel@edk2.groups.io; Kinney, Michael D
> <michael.d.kinney@intel.com>; Sean Brogan <spbrogan@outlook.com>;
> Oliver Smith-Denny <osde@linux.microsoft.com>; Pedro Falcato
> <pedro.falcato@gmail.com>
> Cc: Rebecca Cran <rebecca@bsdio.com>
> Subject: [PATCH edk2-CCodingStandardsSpecification v2 1/1] Prefer use
> of `static` C keyword over EDK2 type `STATIC`
> 
> A while ago a decision was made on the edk2-devel mailing list that
> the `STATIC` EDK2 type should be replaced with the C keyword `static`.
> Following further discussion, it was decided to disallow static local
> variables to prevent breakage when using GoogleTest.
> 
> Update the Coding Specification to match. While here, remove the
> outdated section disallowing static functions since they're no longer
> a problem.
> 
> Bump the revision to 2.4.
> 

Need to add:

Contributed-under: TianoCore Contribution Agreement 1.1

> Signed-off-by: Rebecca Cran <rebecca@bsdio.com>
> ---
>  5_source_files/54_code_file_structure.md    | 9 ++-------
>  5_source_files/56_declarations_and_types.md | 2 +-
>  README.md                                   | 3 ++-
>  book.json                                   | 2 +-
>  4 files changed, 6 insertions(+), 10 deletions(-)
> 
> diff --git a/5_source_files/54_code_file_structure.md
> b/5_source_files/54_code_file_structure.md
> index 0c4d6a26820c..c286b273fe42 100644
> --- a/5_source_files/54_code_file_structure.md
> +++ b/5_source_files/54_code_file_structure.md
> @@ -269,7 +269,8 @@ other than at the top level of a file as specified
> by this document.
> 
>  #### 5.4.2.2 Static
> 
> -An object declared `STATIC` has either file or block scope.
> +An object declared `static` has file scope.
> +Objects may not be declared 'static' within functions.
> 
>  ##### 5.4.2.2.1 Do not reuse an object or function identifier with
> static storage duration.
> 
> @@ -277,9 +278,3 @@ Throughout the set of source files defined within
> a single .inf file, do not
>  reuse an identifier with static storage duration. The compiler may
> not be
>  confused by this, but the user may confuse unrelated variables with
> the same
>  name.
> -
> -##### 5.4.2.2.2 Functions should not be declared STATIC.
> -
> -Some source-level debuggers are unable to resolve static functions.
> Until it
> -can be verified that no one is dependent upon a debugger with this
> limitation,
> -it is strongly recommended that functions not be declared static.
> diff --git a/5_source_files/56_declarations_and_types.md
> b/5_source_files/56_declarations_and_types.md
> index ec1803d980e1..77e3ce99c457 100644
> --- a/5_source_files/56_declarations_and_types.md
> +++ b/5_source_files/56_declarations_and_types.md
> @@ -38,7 +38,7 @@
>  Any abstract type that is defined must be constructed from other
> abstract types
>  or from common EFI data types.
> 
> -#### 5.6.1.2 The use of int, unsigned, char, void, static, long is a
> violation of the coding convention.
> +#### 5.6.1.2 The use of int, unsigned, char, void, long is a
> violation of the coding convention.
> 
>  The corresponding EFI types must be used instead.
> 
> diff --git a/README.md b/README.md
> index 77cfdc8906b1..a8da462c3c46 100644
> --- a/README.md
> +++ b/README.md
> @@ -114,4 +114,5 @@ Copyright (c) 2006-2017, Intel Corporation. All
> rights reserved.
>  |          |
> [#425](https://bugzilla.tianocore.org/show_bug.cgi?id=425) [CCS]
> clarify line breaking and indentation requirements for multi-line
> function calls |            |
>  |          |
> [#1656](https://bugzilla.tianocore.org/show_bug.cgi?id=1656) Update
> all Wiki pages for the BSD+Patent license change with SPDX identifiers
> |            |
>  |          |
> [#607](https://bugzilla.tianocore.org/show_bug.cgi?id=607) Document
> code comment requirements for spurious variable assignments
> |            |
> -| 2.3      | Add 4.2 Directory names section and update File names
> section for the guidelines of module directory and file
> naming|September 2022||
> +| 2.3      | Add 4.2 Directory names section and update File names
> section for the guidelines of module directory and file naming
> |September 2022|
> +| 2.4      | The use of the 'static' C keyword is now preferred over
> the EDK2 type 'STATIC'
> |February 2025|
> diff --git a/book.json b/book.json
> index d112b26e3ebf..a46c487e1b5c 100644
> --- a/book.json
> +++ b/book.json
> @@ -2,7 +2,7 @@
>    "variables" : {
>      "draft"   : "yes",
>      "title"   : "EDK II C Coding Standards Specification",
> -    "version" : "Revision 2.2"
> +    "version" : "Revision 2.4"

Version is ignored when "draft" is "yes", so this change can be dropped.

book.json should only be updated in a release branch to publish a new release.

>    },
>    "plugins": ["puml-aleung"],
>    "pluginsConfig": {}
> --
> 2.48.1



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#121069): https://edk2.groups.io/g/devel/message/121069
Mute This Topic: https://groups.io/mt/110968939/7686176
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io]
-=-=-=-=-=-=-=-=-=-=-=-

Re: [edk2-devel] [PATCH edk2-CCodingStandardsSpecification v2 1/1] Prefer use of `static` C keyword over EDK2 type `STATIC`

[Rebecca Cran]

On 2/3/25 11:17 AM, Kinney, Michael D wrote:
> Version is ignored when "draft" is "yes", so this change can be dropped.
>
> book.json should only be updated in a release branch to publish a new release.


Do we have a process to make sure book.json is updated? It looks like 
version 2.3 was missed.

Also, should I keep the change mentioning version 2.4 in README.md? Or 
will that be updated in the release branch too?

I'll send out a v3 soon.

-- 

Rebecca



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#121071): https://edk2.groups.io/g/devel/message/121071
Mute This Topic: https://groups.io/mt/110968939/7686176
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io]
-=-=-=-=-=-=-=-=-=-=-=-

Re: [edk2-devel] [PATCH edk2-CCodingStandardsSpecification v2 1/1] Prefer use of `static` C keyword over EDK2 type `STATIC`

[Michael D Kinney via groups.io]

Release process is documented here

    https://github.com/tianocore-docs/edk2-TemplateSpecification/wiki/TianoCore-Documents-Releasing

The "version" field in the main branch is ignored, so there is never any reason to change it.
That field typically contains the value when the document was imported into GitHub.
Version 2.3 was not missed.  It is set to that value in the release branch for 2.3.
	
    https://github.com/tianocore-docs/edk2-CCodingStandardsSpecification/tree/release/2.30

Change made in a commit on that release branch:

    https://github.com/tianocore-docs/edk2-CCodingStandardsSpecification/commit/d4735e4d57c8336c19c94fc33367a2b41c0193ff

The change history in Readme.MD are correct.

Mike


> -----Original Message-----
> From: Rebecca Cran <rebecca@bsdio.com>
> Sent: Monday, February 3, 2025 10:29 AM
> To: Kinney, Michael D <michael.d.kinney@intel.com>;
> devel@edk2.groups.io; Sean Brogan <spbrogan@outlook.com>; Oliver
> Smith-Denny <osde@linux.microsoft.com>; Pedro Falcato
> <pedro.falcato@gmail.com>
> Subject: Re: [PATCH edk2-CCodingStandardsSpecification v2 1/1] Prefer
> use of `static` C keyword over EDK2 type `STATIC`
> 
> On 2/3/25 11:17 AM, Kinney, Michael D wrote:
> > Version is ignored when "draft" is "yes", so this change can be
> dropped.
> >
> > book.json should only be updated in a release branch to publish a
> new release.
> 
> 
> Do we have a process to make sure book.json is updated? It looks like
> version 2.3 was missed.
> 
> Also, should I keep the change mentioning version 2.4 in README.md? Or
> will that be updated in the release branch too?
> 
> I'll send out a v3 soon.
> 
> --
> 
> Rebecca



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#121073): https://edk2.groups.io/g/devel/message/121073
Mute This Topic: https://groups.io/mt/110968939/7686176
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io]
-=-=-=-=-=-=-=-=-=-=-=-