Patchwork support for multiarch systems

login
register
mail settings
Submitter Matthias Klose
Date May 11, 2012, 6:33 p.m.
Message ID <4FAD5B61.70209@ubuntu.com>
Download mbox | patch
Permalink /patch/158568/
State New
Headers show

Comments

Matthias Klose - May 11, 2012, 6:33 p.m.
On 11.05.2012 12:51, Paolo Bonzini wrote:
> Il 11/05/2012 07:13, Matthias Klose ha scritto:
>> ok, I did clarify it in the existing documentation of MULTIARCH_DIRNAME in
>> fragments.texi, detailing the search order for the files. Should the search
>> order be mentioned in some user documentation as well? if yes, where?
> 
> Thanks!  I don't think the search order should be mentioned specially,
> since anyway *_INCLUDE_PATH and LIBRARY_PATH are mentioned.  However
> under MULTILIB_DIRNAMES I would add something like this:
> 
> @code{MULTILIB_DIRNAMES} describes the multilib directories using GCC
> conventions and is applied to directories that are part of the GCC
> installation.  When multilib-enabled, the compiler will add a
> subdirectory of the form @var{prefix}/@var{multilib} before each
> directory in the search path for libraries and crt files.

done.

>> +@findex MULTILIB_OSDIRNAMES
>> +@item MULTILIB_OSDIRNAMES
>> +If @code{MULTILIB_OPTIONS} is used, this variable specifies
> 
> ... a list of subdirectory names, that are used to modify the search
> path depending on the chosen multilib.  Unlike @code{MULTILIB_DIRNAMES},
> @code{MULTILIB_OSDIRNAMES} describes the multilib directories using
> operating systems conventions, and is applied to the directories such as
> @code{lib} or those in the @env{LIBRARY_PATH} environment variable.
> 
>>  The format is either the same as of
>> +@code{MULTILIB_DIRNAMES}, or a set of mappings.  When it is the same
>> +as @code{MULTILIB_DIRNAMES}, it describes the multilib directories
>> +using OS conventions, rather than GCC conventions.
> 
> s/OS/operating system/

done.

>> When it is a set
>> +of mappings of the form @var{gccdir}=@var{osdir}, the left side gives
>> +the GCC convention and the right gives the equivalent OS defined
>> +location.  If the @var{osdir} part begins with a @samp{!},
> 
> ... GCC will not search in the non-multilib directory and use
> exclusively the multilib directory.  Otherwise, the compiler will
> examine the search path for libraries and crt files twice; the first
> time it will add @var{multilib} to each directory in the search path,
> the second it will not.
> 
>> Use the mapping when there is
>> +no one-to-one equivalence between GCC levels and the OS.
> 
> I'm not sure what you mean here?

The whole paragraph was taken from the genmultilib script. I left it out for
this version. I think I'll update the genmultilib script when these docs are
settled.

>> +For multilib enabled configurations (see @code{MULTIARCH_DIRNAME})
>> +below), the multilib name is appended to each directory name, separated
>> +by a colon (e.g. @samp{../lib:x86_64-linux-gnu}).
> 
> For configurations that support both multilib and multiarch,
> @code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus
> subsuming @code{MULTIARCH_DIRNAME}.  The multiarch name is appended to
> each directory name, separated by a colon (e.g.
> @samp{../lib32:i386-linux-gnu}).
> 
> Each multiarch subdirectory will be searched before the corresponding OS
> multilib directory, for example @samp{/lib/i386-linux-gnu} before
> @samp{/lib/..lib32}.  The multiarch name will also be used to modify the
> system header search path, as explained for @code{MULTIARCH_DIRNAME}.

done.

>> +@findex MULTIARCH_DIRNAME
>> +@item MULTIARCH_DIRNAME
>> +If @code{MULTIARCH_DIRNAME} is used, this variable specifies the
>> +multiarch name for this configuration.
>>
>> +Libraries and crt files are searched first in
>> +@var{prefix}/@var{multiarch} before @var{prefix} for each @var{prefix}
>> +added by @code{add_prefix} or @code{add_sysrooted_prefix}.
>> +System header files are searched first in
>> +@code{LOCAL_INCLUDE_DIR}/@var{multiarch} before
>> +@code{LOCAL_INCLUDE_DIR}, and in
>> +@code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch} before
>> +@code{NATIVE_SYSTEM_HEADER_DIR}.
>>
>> +@code{MULTIARCH_DIRNAME} is not used for multilib enabled
>> +configurations, but encoded in @code{MULTILIB_OSDIRNAMES} instead.
> 
> This sounds simpler, and doesn't refer to GCC implementation details
> such add_prefix/add_sysrooted_prefix:
> 
> This variable specifies the multiarch name for configurations that are
> multiarch-enabled but not multilibbed configurations.
> 
> The multiarch name is used to augment the search path for libraries, crt
> files and system header files with additional locations.  The compiler
> will add a multiarch subdirectory of the form
> @var{prefix}/@var{multiarch} before each directory in the library and
> crt search path.  It will also add two directories
> @code{LOCAL_INCLUDE_DIR}/@var{multiarch} and
> @code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header
> search path, respectively before @code{LOCAL_INCLUDE_DIR} and
> @code{NATIVE_SYSTEM_HEADER_DIR}.
> 
> @code{MULTIARCH_DIRNAME} is not used for configurations that support
> both multilib and multiarch.  In that case, multiarch names are encoded
> in @code{MULTILIB_OSDIRNAMES} instead.

done. thanks for the wording.

>> +The multiarch tuples are defined
>> +in @uref{http://wiki.debian.org/Multiarch/Tuples}.
> 
> Is this needed?  Aren't they defined simply by the GCC source code?
> Surely if some other OS implements multiarch with different tuples (no
> matter how undesirable that would be) Debian would not be an
> authoritative source.

well, Joseph did ask for some kind of authoritative definition before this patch
could get in. If talking about the "definition" is too strong, then maybe
something along the lines "For more information about multiarch, please see
http://wiki.debian.org/Multiarch/Tuples" would be better?

  Matthias

PS: I'll be on vacation mode for the next two weeks, so might not reply immediately.

Patch

Index: gcc/doc/fragments.texi
===================================================================
--- gcc/doc/fragments.texi	(revision 187337)
+++ gcc/doc/fragments.texi	(working copy)
@@ -93,6 +93,12 @@ 
 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
 as spaces.
 
+@code{MULTILIB_DIRNAMES} describes the multilib directories using GCC
+conventions and is applied to directories that are part of the GCC
+installation.  When multilib-enabled, the compiler will add a
+subdirectory of the form @var{prefix}/@var{multilib} before each
+directory in the search path for libraries and crt files.
+
 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
 @samp{m68000 m68020 msoft-float}.  You may specify a different value if
@@ -152,6 +158,60 @@ 
 of options to be used for all builds.  If you set this, you should
 probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.
 
+@findex MULTILIB_OSDIRNAMES
+@item MULTILIB_OSDIRNAMES
+If @code{MULTILIB_OPTIONS} is used, this variable specifies 
+a list of subdirectory names, that are used to modify the search
+path depending on the chosen multilib.  Unlike @code{MULTILIB_DIRNAMES},
+@code{MULTILIB_OSDIRNAMES} describes the multilib directories using
+operating systems conventions, and is applied to the directories such as
+@code{lib} or those in the @env{LIBRARY_PATH} environment variable.
+The format is either the same as of
+@code{MULTILIB_DIRNAMES}, or a set of mappings.  When it is the same
+as @code{MULTILIB_DIRNAMES}, it describes the multilib directories
+using operating system conventions, rather than GCC conventions.  When it is a set
+of mappings of the form @var{gccdir}=@var{osdir}, the left side gives
+the GCC convention and the right gives the equivalent OS defined
+location.  If the @var{osdir} part begins with a @samp{!},
+GCC will not search in the non-multilib directory and use
+exclusively the multilib directory.  Otherwise, the compiler will
+examine the search path for libraries and crt files twice; the first
+time it will add @var{multilib} to each directory in the search path,
+the second it will not.
+
+For configurations that support both multilib and multiarch,
+@code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus
+subsuming @code{MULTIARCH_DIRNAME}.  The multiarch name is appended to
+each directory name, separated by a colon (e.g.
+@samp{../lib32:i386-linux-gnu}).
+
+Each multiarch subdirectory will be searched before the corresponding OS
+multilib directory, for example @samp{/lib/i386-linux-gnu} before
+@samp{/lib/../lib32}.  The multiarch name will also be used to modify the
+system header search path, as explained for @code{MULTIARCH_DIRNAME}.
+
+@findex MULTIARCH_DIRNAME
+@item MULTIARCH_DIRNAME
+This variable specifies the multiarch name for configurations that are
+multiarch-enabled but not multilibbed configurations.
+
+The multiarch name is used to augment the search path for libraries, crt
+files and system header files with additional locations.  The compiler
+will add a multiarch subdirectory of the form
+@var{prefix}/@var{multiarch} before each directory in the library and
+crt search path.  It will also add two directories
+@code{LOCAL_INCLUDE_DIR}/@var{multiarch} and
+@code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header
+search path, respectively before @code{LOCAL_INCLUDE_DIR} and
+@code{NATIVE_SYSTEM_HEADER_DIR}.
+
+@code{MULTIARCH_DIRNAME} is not used for configurations that support
+both multilib and multiarch.  In that case, multiarch names are encoded
+in @code{MULTILIB_OSDIRNAMES} instead.
+
+More documentation about multiarch can be found at
+@uref{http://wiki.debian.org/Multiarch}.
+
 @findex SPECS
 @item SPECS
 Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since