mirror of
https://github.com/gnustep/tools-make.git
synced 2025-05-11 22:10:38 +00:00
Documentation for new make option (and remove some obsolete documentation)
This commit is contained in:
rfm
parent
1493a378c7
commit
16148bc3d8
3 changed files with 72 additions and 71 deletions
|
|
@ -52,11 +52,11 @@ it's not possible to have an application compiled for NeXT PDO that
|
|||
runs with gnustep-base or vice-versa. To summarize, an application can
|
||||
be compiled for these combinations:
|
||||
|
||||
Objective-C runtime: NeXT, GNU
|
||||
Objective-C runtime: NeXT, GNU, GNUstep/Apple
|
||||
Foundation library: NeXT, PDO, gnustep-base, libFoundation
|
||||
GUI library: NeXT, gnustep-gui
|
||||
|
||||
Objective-C runtime: nx (for NeXT), gnu (for GNU)
|
||||
Objective-C runtime: nx (for NeXT), gnu (for GNU), ng (for Next Generation (GNUstep or Apple for ObjC-2)
|
||||
Foundation library: nx (for NeXT), pdo (for PDO), gnu (for gnustep-base),
|
||||
fd (for libFoundation)
|
||||
GUI library: nx (for NeXT), gnu (for gnustep-gui)
|
||||
|
|
@ -80,6 +80,7 @@ ObjC runtime Foundation GUI
|
|||
gnu gnu gnu
|
||||
nx fd gnu
|
||||
gnu fd gnu
|
||||
ng gnu gnu
|
||||
|
||||
Note that one can choose his/her own packages to build; it is not
|
||||
required to have all the packages installed on the system. Not having
|
||||
|
|
@ -339,15 +340,20 @@ if the target needs to be built as a shared library. On systems that support
|
|||
shared libraries this is the default; the user has to explicitly specify
|
||||
shared=no in the command line.
|
||||
|
||||
* asan
|
||||
|
||||
When this variable is yes, an address and leak sanitized version of the target
|
||||
is built. The default is no.
|
||||
|
||||
* profile
|
||||
|
||||
When this variable is yes, a profile version of the target is built. The
|
||||
default is no.
|
||||
|
||||
For example if you want to build a shared library with debug information
|
||||
enabled but no profile information, the command line would be:
|
||||
and sanitization enabled but no profile information, the command line would be:
|
||||
|
||||
$ make shared=yes debug=yes profile=no
|
||||
$ make shared=yes debug=yes asan=yes profile=no
|
||||
|
||||
The last argument is not necessary because the default is to build a version
|
||||
without profile information.
|
||||
|
|
@ -358,62 +364,6 @@ profile is turned on the output directory would be shared_profile_debug_obj.
|
|||
Of course you also have to specify the library combo if it's different than the
|
||||
default.
|
||||
|
||||
Naming conventions of the libraries
|
||||
===================================
|
||||
|
||||
Sometimes you need to have different versions of a library compiled with
|
||||
different options. Suppose you want to compile a library with profiling
|
||||
information enabled so that you can profile your code. But you don't want to
|
||||
overwrite your existing installed library so that only some of the applications
|
||||
will work with the profile library, the rest will still use the normal library.
|
||||
|
||||
The makefile package supports such a schema by having different names for
|
||||
different types of the same library. This works by appending an underscore
|
||||
after the name of the library followed by a letter which indicates the type of
|
||||
the library:
|
||||
|
||||
's' for a static library
|
||||
'p' for a profile library
|
||||
'd' for a debug library
|
||||
|
||||
So for example if you have the library 'example' compiled with debug
|
||||
information as a shared library it would be named libexample_d.so. If the same
|
||||
library is compiled as a static library its name would be named
|
||||
libexample_sd.a. The reason why the 's' letter for the static library appears
|
||||
in name of the library is for systems where the extensions of libraries don't
|
||||
matter.
|
||||
|
||||
It is possible to compile a library with whatever combination of flags you
|
||||
want. The letters are appended in the order specified above, so if you compile
|
||||
the library as a static library, with profile and debug information enabled,
|
||||
the library name will have the _spd suffix appended.
|
||||
|
||||
How a library is chosen
|
||||
=======================
|
||||
|
||||
What happens if you compile an application with profile enabled and you don't
|
||||
have a library compiled with profile info into it, but you do have a normal
|
||||
library installed? It would be great if the normal library is chosen instead.
|
||||
This is a problem because the library that should be chosen has a different
|
||||
name than the profile library.
|
||||
|
||||
We do support this schema by requiring the libraries to be specified using the
|
||||
short name, without any suffix appended to it. The `example' library in our
|
||||
case should be passed to the linker using -lexample, and not using -lexample_p.
|
||||
Based upon the shared, profile and debug variables, the makefile package will
|
||||
identify which are the libraries that exist on the system and it will come with
|
||||
the correct names when linking.
|
||||
|
||||
The search order of libraries depending on what type of library is required is
|
||||
as follows. First of all an exact match is searched; if one is found it is
|
||||
returned. If either debug or profile are required, a library that matches at
|
||||
least one of these attributes is returned. For example if there is a
|
||||
profile+debug version of a library but only debug is required this library will
|
||||
match. If a static version is required but no static versions of the library
|
||||
exist, then no library is chosen; in this case the system simply prints out the
|
||||
name of the library, assuming a static library is somewhere else in the
|
||||
libraries search path of the linker.
|
||||
|
||||
Building applications
|
||||
=====================
|
||||
|
||||
|
|
@ -428,15 +378,7 @@ the application wrapper and it contains the binaries for various architectures
|
|||
and resources needed by the application.
|
||||
|
||||
The name of the application wrapper is taken to be the name of the application
|
||||
with the following extensions:
|
||||
|
||||
.profile - if the application has been built with profile enabled
|
||||
.debug - if the application has been built with debug enabled
|
||||
.app - if the application has been built without debug or profile enabled
|
||||
|
||||
If both debug and profile are enabled, the application extension will simply
|
||||
have the .profile extension. This is different from libraries were both options
|
||||
are reflected into the library's name.
|
||||
with the .app extension.
|
||||
|
||||
The structure of makefiles
|
||||
==========================
|
||||
|
|
@ -483,4 +425,4 @@ The makefile package is installed under $(GNUSTEP_SYSTEM_ROOT)/Library/Makefiles
|
|||
|
||||
Ovidiu Predescu
|
||||
|
||||
Last updated: April, 2001
|
||||
Last updated: Jan, 2025
|
||||
|
|
|
|||
|
|
@ -102,6 +102,7 @@ This is all that is necessary to define the project.
|
|||
@menu
|
||||
* Debug Information::
|
||||
* Profile Information::
|
||||
* Memory Sanitisation::
|
||||
* Library Types::
|
||||
@end menu
|
||||
|
||||
|
|
@ -123,7 +124,7 @@ not put into the binary files.
|
|||
make debug=no
|
||||
@end smallexample
|
||||
|
||||
@node Profile Information, Library Types, Debug Information, Running Make
|
||||
@node Profile Information, Memory Sanitisation, Debug Information, Running Make
|
||||
@section Profile Information
|
||||
|
||||
By default the Makefile Package does not tell the compiler to generate
|
||||
|
|
@ -136,6 +137,56 @@ put into the binary files.
|
|||
make profile=yes
|
||||
@end smallexample
|
||||
|
||||
@node Memory Sanitisation, Library Types, Profile Information, Running Make
|
||||
@section Memory Sanitisation
|
||||
|
||||
Production code must not use memory sanitization tools, but during development
|
||||
and debugging these can be extremely useful, so the Makefile Package provides
|
||||
an option to tell the compiler to generate output for address and leak
|
||||
sanitization using https://github.com/google/sanitizers/wiki/addresssanitizer
|
||||
|
||||
Unfortunately, AddressSanitizer/LeakSanitizer is not particularly portable and
|
||||
is available on a limited selection of hardware and operating systems, so
|
||||
turnign it on in GNUstep-make may not actually work on your system.
|
||||
|
||||
The following command illustrates how to tell the Makefile Package to pass
|
||||
the appropriate flags to the compiler so that sanitization is put into the
|
||||
binary fnd so that the preprocessor can be used to change code behavior when
|
||||
it is built for sanitization (-fsanitize=address and -DGNUSTEP_WITH_ASAN=1).
|
||||
|
||||
@smallexample
|
||||
make asan=yes
|
||||
@end smallexample
|
||||
|
||||
You can get the same effect by setting an environment variable as follows:
|
||||
@smallexample
|
||||
export GNUSTEP_WITH_ASAN=1
|
||||
@end smallexample
|
||||
|
||||
When you build libraries, frameworks, or bundles with sanitization turned on,
|
||||
you must also use ASAN to build any apps or tools which use them. This
|
||||
is because the library/framework/bundle will have dependencies on the leak
|
||||
sanitization shared library, and those dependencies must be fulfilled when
|
||||
the app/tool is linked.
|
||||
|
||||
The basic effect of sanitization is that, in the event of an address error
|
||||
(when the code attempts to access memory it shouldn't), the app/tool is
|
||||
immediately terminated with details of the problem printed to stderr, and
|
||||
in the event of memory leaks (detected at app/tool exit) a report of the
|
||||
locations of the leaks is printed to stderr.
|
||||
|
||||
Beware that an app/tool built with ASAN maps a huge amount of virtual memory
|
||||
to help it detect memory violations in the code, and while this virtual memory
|
||||
usage does not require real memory, it does mean that processes monitoring the
|
||||
memory usage of your app/tool will give completely meaningless results.
|
||||
|
||||
Beware also, that an app/tool built with ASAN does use considerably more real
|
||||
memory than normal, and its usage of memory continually grows, because it is
|
||||
keeping records of what the app/tool does with memory in order to be able to
|
||||
perform leak analysis and reporting when the app/tool finishes.
|
||||
If you have many apps/tools under test concurrently and for a long time, your
|
||||
system may run out of memory.
|
||||
|
||||
@node Library Types, , Profile Information, Running Make
|
||||
@section Static, Shared, and Dynamic Link Libraries
|
||||
|
||||
|
|
|
|||
|
|
@ -4,6 +4,14 @@ The release notes include descriptions of API changes, behavior
|
|||
changes and other information that might help developers and users
|
||||
migrate to using a newer version of the make system.
|
||||
|
||||
@section Version 2.9.3
|
||||
|
||||
Addition of the 'asan=yes' option when GNUstep-make is invoked and support
|
||||
for the GNUSTEP_WITH_ASAN=1 environment setting to turn on address and leak
|
||||
sanitisation.
|
||||
|
||||
Various minor fixes
|
||||
|
||||
@section Version 2.9.2
|
||||
|
||||
Changes to work around the removal of the javah tool after java version 8.
|
||||
|
|
|
|||
Loading…
Reference in a new issue