[PATCH] scripts: Explain the difference between linux-headers and standard-headers

[PATCH] scripts: Explain the difference between linux-headers and standard-headers

[Thomas Huth]

If you don't know it, it's hard to figure out the difference between
the linux-headers folder and the include/standard-headers folder.
So let's add a short explanation to clarify the difference.

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 scripts/update-linux-headers.sh | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/scripts/update-linux-headers.sh b/scripts/update-linux-headers.sh
index fea4d6eb65..96c7daef94 100755
--- a/scripts/update-linux-headers.sh
+++ b/scripts/update-linux-headers.sh
@@ -9,6 +9,13 @@
 #
 # This work is licensed under the terms of the GNU GPL version 2.
 # See the COPYING file in the top-level directory.
+#
+# The script will copy the headers into two target folder:
+#
+# - linux-headers/ for file that are required for compiling on a Linux host
+#
+# - include/standard-headers/ for files that are used for guest device emulation
+#
 
 tmpdir=$(mktemp -d)
 linux="$1"
-- 
2.27.0

Re: [PATCH] scripts: Explain the difference between linux-headers and standard-headers

[Peter Maydell]

On Thu, 9 Dec 2021 at 17:34, Thomas Huth <thuth@redhat.com> wrote:
>
> If you don't know it, it's hard to figure out the difference between
> the linux-headers folder and the include/standard-headers folder.
> So let's add a short explanation to clarify the difference.
>
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  scripts/update-linux-headers.sh | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/scripts/update-linux-headers.sh b/scripts/update-linux-headers.sh
> index fea4d6eb65..96c7daef94 100755
> --- a/scripts/update-linux-headers.sh
> +++ b/scripts/update-linux-headers.sh
> @@ -9,6 +9,13 @@
>  #
>  # This work is licensed under the terms of the GNU GPL version 2.
>  # See the COPYING file in the top-level directory.
> +#
> +# The script will copy the headers into two target folder:

"folders"

> +#
> +# - linux-headers/ for file that are required for compiling on a Linux host

"files"

> +#
> +# - include/standard-headers/ for files that are used for guest device emulation
> +#


We could expand on this a little if you like, eg:

- linux-headers/ for files that are required for compiling on a Linux host.
  Generally we have these so we can use kernel structs and defines that
  are more recent than the headers that might be in /usr/include/linux
  on the host system. Usually this script can do simple file copies
  for these headers.

- include/standard-headers/ for files that are used for guest device emulation
  and are required on all hosts. For instance, we get our definitions of the
  virtio structures from the Linux kernel headers, but we need those
  definitions regardless of which host OS we are building on. This script
  has to be careful to sanitize the headers to remove any use of Linux-specifics
  such as types like "__u64". This work is done in the cp_portable function.

-- PMM

Re: [PATCH] scripts: Explain the difference between linux-headers and standard-headers

[Thomas Huth]

On 09/12/2021 18.44, Peter Maydell wrote:
> On Thu, 9 Dec 2021 at 17:34, Thomas Huth <thuth@redhat.com> wrote:
>>
>> If you don't know it, it's hard to figure out the difference between
>> the linux-headers folder and the include/standard-headers folder.
>> So let's add a short explanation to clarify the difference.
>>
>> Signed-off-by: Thomas Huth <thuth@redhat.com>
>> ---
>>   scripts/update-linux-headers.sh | 7 +++++++
>>   1 file changed, 7 insertions(+)
>>
>> diff --git a/scripts/update-linux-headers.sh b/scripts/update-linux-headers.sh
>> index fea4d6eb65..96c7daef94 100755
>> --- a/scripts/update-linux-headers.sh
>> +++ b/scripts/update-linux-headers.sh
>> @@ -9,6 +9,13 @@
>>   #
>>   # This work is licensed under the terms of the GNU GPL version 2.
>>   # See the COPYING file in the top-level directory.
>> +#
>> +# The script will copy the headers into two target folder:
> 
> "folders"
> 
>> +#
>> +# - linux-headers/ for file that are required for compiling on a Linux host
> 
> "files"
> 
>> +#
>> +# - include/standard-headers/ for files that are used for guest device emulation
>> +#
> 
> 
> We could expand on this a little if you like, eg:
> 
> - linux-headers/ for files that are required for compiling on a Linux host.
>    Generally we have these so we can use kernel structs and defines that
>    are more recent than the headers that might be in /usr/include/linux
>    on the host system. Usually this script can do simple file copies
>    for these headers.
> 
> - include/standard-headers/ for files that are used for guest device emulation
>    and are required on all hosts. For instance, we get our definitions of the
>    virtio structures from the Linux kernel headers, but we need those
>    definitions regardless of which host OS we are building on. This script
>    has to be careful to sanitize the headers to remove any use of Linux-specifics
>    such as types like "__u64". This work is done in the cp_portable function.

Sounds like a very good idea! Could you please send this as a patch (since 
this wouldn't be my own words anymore)?

  Thomas