1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename gnustep-make.info 4@settitle GNUstep Makefile Package 5@c %**end of header 6 7@smallbook 8@setchapternewpage odd 9 10@dircategory Software development 11@direntry 12* GNUstep Make: (gnustep-make). The GNUstep build system. 13@end direntry 14 15@ifinfo 16 17Copyright @copyright{} 2000 Free Software Foundation, Inc. 18 19Permission is granted to copy, distribute and/or modify this document 20under the terms of the GNU Free Documentation License, Version 1.1 or 21any later version published by the Free Software Foundation. 22 23@end ifinfo 24 25@titlepage 26 27@title GNUstep Makefile Package 28 29@page 30 31@vskip 0pt plus 1filll 32Copyright @copyright{} 2000 Free Software Foundation, Inc. 33 34@sp 1 35Permission is granted to copy, distribute and/or modify this document 36under the terms of the GNU Free Documentation License, Version 1.1 or 37any later version published by the Free Software Foundation. 38 39@end titlepage 40 41@contents 42 43@page 44 45@c Makefile Package Chapter 46@node Top, Makefile Introduction, (dir), (dir) 47@chapter Makefile Package 48 49@menu 50* Makefile Introduction:: 51* Makefile Structure:: 52* Running Make:: 53* Project Types:: 54* GNUmakefile.preamble:: 55* GNUmakefile.postamble:: 56* Common Variables:: 57* Other Variables:: 58@end menu 59 60@node Makefile Introduction, Makefile Structure, Top, Top 61@section Introduction 62 63The Makefile package is a system of make commands that is designed to 64encapsulate all the complex details of building and installing various types 65of projects from libraries to applications to documentation. This frees the 66developer to focus on the details of their particular project. Only 67a fairly simple main makefile need to be written which specifies the 68type of project and files involved in the project. 69 70@node Makefile Structure, Running Make, Makefile Introduction, Top 71@section Structure of a Makefile 72 73Here is an example makefile (named GNUmakefile to emphasis the fact that it relies on special features of the GNU make program). 74 75@smallexample 76# 77# An example GNUmakefile 78# 79 80# Include the common variables defined by the Makefile Package 81include $(GNUSTEP_MAKEFILES)/common.make 82 83# Build a simple Objective-C program 84TOOL_NAME = simple 85 86# The Objective-C files to compile 87simple_OBJC_FILES = simple.m 88 89-include GNUmakefile.preamble 90 91# Include in the rules for making GNUstep command-line programs 92include $(GNUSTEP_MAKEFILES)/tool.make 93 94-include GNUmakefile.postamble 95@end smallexample 96 97This is all that is necessary to define the project. 98 99 100@node Running Make, Project Types, Makefile Structure, Top 101@section Running Make 102@menu 103* Debug Information:: 104* Profile Information:: 105* Library Types:: 106@end menu 107 108Normally to compile a package which uses the Makefile Package it is 109purely a matter of typing @code{make} from the top-level directory of 110the package, and the package is compiled without any additional 111interaction. 112 113@node Debug Information, Profile Information, Running Make, Running Make 114@subsection Debug Information 115 116By default the Makefile Package tells the compiler to generate 117debugging information when compiling Objective-C and C files. The 118following command illustrates how to tell the Makefile Package to pass 119the appropriate flags to the compiler so that debugging information is 120not put into the binary files. 121 122@smallexample 123make debug=no 124@end smallexample 125 126@node Profile Information, Library Types, Debug Information, Running Make 127@subsection Profile Information 128 129By default the Makefile Package does not tell the compiler to generate 130profiling information when compiling Objective-C and C files. The 131following command illustrates how to tell the Makefile Package to pass 132the appropriate flags to the compiler so that profiling information is 133put into the binary files. 134 135@smallexample 136make profile=yes 137@end smallexample 138 139@node Library Types, , Profile Information, Running Make 140@subsection Static, Shared, and Dynamic Link Libraries 141 142By default the Makefile Package will generate a shared library if it is 143building a library project type, and it will link with shared libraries 144if it is building an application or command line tool project type. The 145following command illustrates how to tell the Makefile Package not to 146build using shared libraries but using static libraries instead. 147 148@smallexample 149make shared=no 150@end smallexample 151 152This default is only applicable on systems that support shared 153libraries; systems that do not support shared libraries will always 154build using static libraries. Some systems support dynamic link 155libraries (DLL) which are a form of shared libraries; on these systems, 156DLLs will be built by default unless the Makefile Package is told to 157build using static libraries instead, as in the above command. 158 159@node Project Types, GNUmakefile.preamble, Running Make, Top 160@section Project Types 161@menu 162* aggregate.make:: 163* application.make:: 164* bundle.make:: 165* ctool.make:: 166* documentation.make:: 167* framework.make:: 168* java.make:: 169* library.make:: 170* native-library.make:: 171* nsis.make:: 172* objc.make:: 173* palette.make:: 174* rpm.make:: 175* service.make:: 176* subproject.make:: 177* tool.make:: 178@end menu 179 180Projects are divided into different types described below. To create a 181project of a specific type, just include the particular makefile. For 182example, to create an application, include this line in your main make 183file: 184 185@example 186include $(GNUSTEP_MAKEFILES)/application.make 187@end example 188 189Each project type is independent of the others. If you want to create 190two different types of projects within the same directory (e.g. a tool 191and a java program), include both the desired makefiles in your main 192make file. 193 194The documentation for variables used to control each project type is 195provided at the start of each individual makefile (common.make and rules.make 196document more general variables). 197 198The documentation for installing resources (a feature shared by many project 199types) is in resource-set.make. 200 201 202@node aggregate.make, application.make, Project Types, Project Types 203@subsection Aggregate (@file{aggregate.make}) 204 205An Aggregate project is a project that consists of several 206subprojects. Each subproject can be of any other valid project type 207(including the Aggregate type). The only project variable is the 208SUBPROJECTS variable 209 210@defvr {Aggregate project} SUBPROJECTS 211@code{SUBPROJECTS} defines the directory names that hold the subprojects 212that the Aggregate project should build. 213@end defvr 214 215@node application.make, bundle.make, aggregate.make, Project Types 216@subsection Graphical Applications (@file{application.make}) 217 218An application is an Objective-C program that includes a GUI component, 219and by default links in all the GNUstep libraries required for GUI 220development, such as the Base and Gui libraries. 221 222@node bundle.make, ctool.make, application.make, Project Types 223@subsection Bundles (@file{bundle.make}) 224 225A bundle is a collection of resources and code that can be used to 226enhance an existing application or tool dynamically using the NSBundle 227class from the GNUstep base library. 228 229@node ctool.make, documentation.make, bundle.make, Project Types 230@subsection Command Line C Tools (@file{ctool.make}) 231 232A ctool is a project that only uses C language files. 233Otherwise it is similar to the ObjC project type. 234 235@node documentation.make, framework.make, ctool.make, Project Types 236@subsection Documentation (@file{documentation.make}) 237 238The Documentation project provides rules to use various types of 239documentation such as texi and LaTeX documentation, and convert them 240into finished documentation (info, PostScript, HTML, etc). 241 242@node framework.make, java.make, documentation.make, Project Types 243@subsection Frameworks (@file{framework.make}) 244 245A Framework is a collection of resources and a library that provides 246common code that can be linked into a Tool or Application. In many 247respects it is similar to a Bundle. 248 249@node java.make, library.make, framework.make, Project Types 250@subsection Java (@file{java.make}) 251 252This project provides rules for building java programs. It also makes it 253easy to make java projects that interact with the GNUstep libraries. 254 255@subsubsection Project Variables 256 257@defvr {Java project} JAVA_PACKAGE_NAME 258@code{JAVA_PACKAGE_NAME} is the reverse DNS style Java package name that 259resides in this project. 260@end defvr 261 262@defvr {Java project} JAVA_FILES 263@code{xxx_JAVA_FILES} is the list of Java source code files, with a 264@file{.java} extension, that are compiled for the @strong{xxx} project. 265@strong{xxx} should be replaced with the name of the Java package 266specified in @code{JAVA_PACKAGE_NAME}. 267@end defvr 268 269@defvr {Java project} JAVA_JNI_FILES 270@code{xxx_JAVA_JNI_FILES} is the list of Java source code files for 271which @code{javah} should produce header files for integration with 272Objective-C code. 273@strong{xxx} should be replaced with the name of the Java package 274specified in @code{JAVA_PACKAGE_NAME}. 275@end defvr 276 277@defvr {Java project} JAVA_PROPERTIES_FILES 278@code{xxx_JAVA_PROPERTIES_FILES} can be used to specify properties files 279to install. 280@strong{xxx} should be replaced with the name of the Java package 281specified in @code{JAVA_PACKAGE_NAME}. 282@end defvr 283 284@defvr {Java project} JAVA_MANIFEST_FILE 285@code{xxx_JAVA_MANIFEST_FILE} can be used to specify a manifest fragment 286that is used when building a jar file for the @strong{xxx} package. 287@strong{xxx} should be replaced with the name of the Java package 288specified in @code{JAVA_PACKAGE_NAME}. 289@end defvr 290 291@defvr {Java project} JAVA_JAR_NAME 292@code{xxx_JAVA_JAR_NAME} can be used to specify a custom name for the jar 293built by @code{make jar}. The default would be the package name (@strong{xxx}) 294with all dots replaced by hyphens. 295@end defvr 296 297@node library.make, native-library.make, java.make, Project Types 298@subsection Libraries (@file{library.make}) 299@menu 300* library.make variables:: 301* Example Library Makefile:: 302@end menu 303 304The Makefile Package provides a project type for building libraries; 305libraries can be built as static libraries, shared libraries, or dynamic 306link libraries (DLL) if the platform supports that type of library. 307Static libraries are supported on all platforms; while, shared libraries 308and DLLs are only supported on some platforms. 309 310@node library.make variables, Example Library Makefile, library.make, library.make 311@subsubsection Project Variables 312 313@defvr {Library project} LIBRARY_NAME 314@code{LIBRARY_NAME} should be assigned the list of name of libraries to 315be generated. Most UNIX systems expect that the filename for the 316library has the word @file{lib} prefixed to the name; i.e. the @file{c} 317library has filename of @file{libc}. Prefix the @file{lib} to the 318library name when it is specified in the @code{LIBRARY_NAME} variable 319because the Makefile Package will not automatically prefix it. 320@end defvr 321 322@defvr {Library project} C_FILES 323@code{xxx_C_FILES} is the list of C files, with a @file{.c} extension, 324that are to be compiled to generate the @strong{xxx} library. 325Replace the @strong{xxx} with the name of the library as listed by 326the @code{LIBRARY_NAME} variable. 327@end defvr 328 329@defvr {Library project} OBJC_FILES 330@code{xxx_OBJC_FILES} is the list of Objective-C files, with a @file{.m} 331extension, that are to be compiled to generate the @strong{xxx} library. 332Replace the @strong{xxx} with the name of the library as listed by the 333@code{LIBRARY_NAME} variable. 334@end defvr 335 336@defvr {Library project} PSWRAP_FILES 337@code{xxx_PSWRAP_FILES} is the list of PostScript wrap files, with a 338@file{.psw} extension, that are to be compiled to generate the 339@strong{xxx} library. PostScript wrap files are processed by the 340@file{pswrap} utility which generates a @file{.c} and a @file{.h} file 341from each @file{.psw} file; the generate @file{.c} file is the file 342actually compiled. Replace the @strong{xxx} with the name of the 343library as listed by the @code{LIBRARY_NAME} variable. 344@end defvr 345 346@defvr {Library project} HEADER_FILES 347@code{xxx_HEADER_FILES} is the list of header filenames that are to be 348installed with the library. If a filename has a directory path prefixed 349to it then that prefix will be maintained when the headers are 350installed. It is up to the user to make sure that the installation 351directory exists; otherwise, an error will occur when the library is 352installed, see @ref{library.make 353variables,,xxx_HEADER_FILES_INSTALL_DIR}. Replace the @strong{xxx} with 354the name of the library as listed by the @code{LIBRARY_NAME} variable. 355@end defvr 356 357@defvr {Library project} HEADER_FILES_DIR 358@code{xxx_HEADER_FILES_DIR} is the relative path from the current 359directory, where the makefile is located, to where the header files 360specified by @code{xxx_HEADER_FILES} are located. If a filename 361specified in @code{xxx_HEADER_FILES} has a directory path prefixed to it 362then that path will not be removed when the Makefile Package accesses 363the files, so do not specify a path with @code{xxx_HEADER_FILES_DIR} 364that is already prefixed to the header filenames, see @ref{library.make 365variables,,xxx_HEADER_FILES_INSTALL_DIR}. @code{xxx_HEADER_FILES_DIR} 366is optional; leaving it blank or undefined, and the Makefile Package 367assumes that the relative path to the header files is the current 368directory where the makefile resides. Replace the @strong{xxx} with the 369name of the library as listed by the @code{LIBRARY_NAME} variable. 370@end defvr 371 372@defvr {Library project} HEADER_FILES_INSTALL_DIR 373@code{xxx_HEADER_FILES_INSTALL_DIR} specifies the relative subdirectory 374path below @code{GNUSTEP_HEADERS} where the header files are to be 375installed. If this directory or any of its parent directories do not 376exist, then the Makefile Package will create them. The Makefile Package 377prefixes @code{xxx_HEADER_FILES_INSTALL_DIR} to each of the filenames in 378@code{xxx_HEADER_FILES} when they are installed, so if the filenames in 379@code{xxx_HEADER_FILES} already have a directory path prefixed then the 380user is responsible for creating that directory, the Makefile Package 381will not create. @code{xxx_HEADER_FILES_INSTALL_DIR} is optional; 382leaving it blank or undefined, and the Makefile Package assumes that the 383installation directory is just @code{GNUSTEP_HEADERS} with no 384subdirectory. Replace the @strong{xxx} with the name of the library as 385listed by the @code{LIBRARY_NAME} variable. 386@end defvr 387 388@defvr {Library project} CPPFLAGS 389@code{xxx_CPPFLAGS} are additional flags that will be passed to the 390compiler preprocessor when compiling Objective-C and C files to generate 391the @strong{xxx} library. Adding flags here does not override the 392default @code{CPPFLAGS}, see @ref{Overridable Flags,,CPPFLAGS}, they are 393in addition to @code{CPPFLAGS}. These flags are specific to the 394@strong{xxx} library, see @ref{GNUmakefile.preamble,,ADDITIONAL_CPPFLAGS}, 395to see how to specify global preprocessor flags. Replace the 396@strong{xxx} with the name of the listed as listed by the 397@code{LIBRARY_NAME} variable. 398@end defvr 399 400@defvr {Library project} OBJCFLAGS 401@code{xxx_OBJCFLAGS} are additional flags that will be passed to the 402compiler when compiling Objective-C files to generate the @strong{xxx} 403library. Adding flags here does not override the default 404@code{OBJCFLAGS}, see @ref{Overridable Flags,,OBJCFLAGS}, they are in 405addition to @code{OBJCFLAGS}. These flags are specific to the 406@strong{xxx} library, see @ref{GNUmakefile.preamble,,ADDITIONAL_OBJCFLAGS}, 407to see how to specify global compiler flags. Replace the @strong{xxx} 408with the name of the library as listed by the @code{LIBRARY_NAME} 409variable. 410@end defvr 411 412@defvr {Library project} CFLAGS 413@code{xxx_CFLAGS} are additional flags that will be passed to the 414compiler when compiling C files to generate the @strong{xxx} library. 415Adding flags here does not override the default @code{CFLAGS}, see 416@ref{Overridable Flags,,CFLAGS}, they are in addition to @code{CFLAGS}. 417These flags are specific to the @strong{xxx} library, see 418@ref{GNUmakefile.preamble,,ADDITIONAL_CFLAGS}, to see how to specify global 419compiler flags. Replace the @strong{xxx} with the name of the library 420as listed by the @code{LIBRARY_NAME} variable. 421@end defvr 422 423@defvr {Library project} LDFLAGS 424@code{xxx_LDFLAGS} are additional flags that will be passed to the 425linker when it creates the @strong{xxx} library. Adding flags here does 426not override the default @code{LDFLAGS}, see @ref{Overridable 427Flags,,LDFLAGS}, they are in addition to @code{LDFLAGS}. These flags 428are specific to the @strong{xxx} library, see 429@ref{GNUmakefile.preamble,,ADDITIONAL_LDFLAGS}, to see how to specify 430global linker flags. Replace the @strong{xxx} with the name of the 431library as listed by the @code{LIBRARY_NAME} variable. 432@end defvr 433 434@defvr {Library project} INCLUDE_DIRS 435@code{xxx_INCLUDE_DIRS} is the list of additional directories that the 436compiler will search when it is looking for include files; these flags 437are specific to the @strong{xxx} library, see 438@ref{GNUmakefile.preamble,,ADDITIONAL_INCLUDE_DIRS}, to see how to specify 439additional global include directories. The directories should be 440specified as @samp{-I} flags to the compiler. The additional include 441directories will be placed before the normal GNUstep and system include 442directories, and before any global include directories specified with 443@code{ADDITIONAL_INCLUDE_DIRS}, so they will always be searched first. 444Replace the @strong{xxx} with the name of the library as listed by the 445@code{LIBRARY_NAME} variable. 446@end defvr 447 448@node Example Library Makefile, , library.make variables, library.make 449@subsubsection Example Makefile 450 451This example makefile illustrates two libraries, @file{libone} and 452@file{libtwo}, that are to be generated. 453 454@smallexample 455# 456# An example GNUmakefile 457# 458 459# Include the common variables defined by the Makefile Package 460include $(GNUSTEP_MAKEFILES)/common.make 461 462# Two libraries 463LIBRARY_NAME = libone libtwo 464 465# 466# The files for the libone library 467# 468# The Objective-C files to compile 469libone_OBJC_FILES = one.m draw.m 470 471# The C source files to be compiled 472libone_C_FILES = parse.c 473 474# The PostScript wrap source files to be compiled 475libone_PSWRAP_FILES = drawing.psw 476 477# The header files for the library 478libone_HEADER_FILES_DIR = ./one 479libone_HEADER_FILES_INSTALL_DIR = one 480libone_HEADER_FILES = one.h draw.h 481 482# 483# The files for the libtwo library 484# 485# The Objective-C files to compile 486libtwo_OBJC_FILES = two.m another.m test.m 487 488# The header files for the library 489libtwo_HEADER_FILES_DIR = ./two 490libtwo_HEADER_FILES_INSTALL_DIR = two 491libtwo_HEADER_FILES = two.h another.h test.h common.h 492 493# Option include to set any additional variables 494-include GNUmakefile.preamble 495 496# Include in the rules for making libraries 497include $(GNUSTEP_MAKEFILES)/library.make 498 499# Option include to define any additional rules 500-include GNUmakefile.postamble 501 502@end smallexample 503 504Notice that the @file{libone} library has Objective-C, C, and PostScript 505wrap files to be compiled; while, the @file{libtwo} library only has 506some Objective-C files. 507 508The header files for the @file{libone} library reside in the @file{one} 509subdirectory from where the sources are located, and the header files 510will be installed into the @file{one} subdirectory within 511@code{GNUSTEP_HEADERS}. Likewise the header files for the @file{libtwo} 512library reside in the @file{two} subdirectory from where the sources are 513located, and the header files will be installed into the @file{two} 514subdirectory within @code{GNUSTEP_HEADERS}. 515 516@node native-library.make, nsis.make, library.make, Project Types 517@subsection Native Library (@file{native-library.make}) 518 519A "native library" is a project which is to be built as a shared 520library on most targets and as a framework on Darwin. (Currently 521this is only the case for apple-apple-apple.) In other 522words, it is to be built as the most appropriate native equivalent 523of a traditional shared library (see @ref{library.make} and 524@ref{framework.make}). 525 526@defvr {Native Library project} NATIVE_LIBRARY_NAME 527@code{NATIVE_LIBRARY_NAME} should be the name of the native library, 528without the 'lib'. All the other variables are the same as 529the ones used in libraries and frameworks. 530@end defvr 531 532To compile something against a native library, you can use 533@code{ADDITIONAL_NATIVE_LIBS += MyLibrary} 534This will be converted into -lMyLibrary link flag on for most 535targets and into -framework MyLibrary link flag for 536apple-apple-apple. 537 538To add the corresponding flags, you can use 539@code{ADDITIONAL_NATIVE_LIB_DIRS += ../MyPath} 540This will be converted into -L../MyPath/$(GNUSTEP_OBJ_DIR) flag 541on for most targets and into -F../MyPath flag for apple-apple-apple. 542 543@node nsis.make, objc.make, native-library.make, Project Types 544@subsection NSIS Installer (@file{nsis.make}) 545 546The NSIS make project provides rules for automatically generating NSIS 547installers for Windows operating systems. In order to get this functionality, 548include @file{Master/nsis.make} from the Makefiles directory in your 549GNUmakefile. 550 551@example 552include $(GNUSTEP_MAKEFILES)/Master/nsis.make 553@end example 554 555To create an installer file by itself, run @code{make nsifile}. To 556create the full installer executable, run @code{make nsis}. Note that in 557order to do this, you must be either running on a Windows computer with 558a release of the NSIS compiler (from @url{http://nsis.sourceforge.net}) or you 559need to be using a cross-compiler and cross-compiled NSIS script compiler. 560(NOTE: This does not currently work - you need to use the GUI NSIS compiler 561to compile the installer scripts). 562 563Currently the nsis make package only makes installers for 564Applications. It will use the @file{nsi-app.template} file in the 565GNUstep Makefiles directory. If you want, you can provide your own 566template with customized script instructions by creating a file called 567@file{PACKAGE_NAME.nsi.in}, where @code{PACKAGE_NAME} is the same as the 568name of your package (see below). 569 570You also need to define several variables in your main make file. 571Except for @code{PACKAGE_NAME}, which is required, all the following 572variables are optional. 573 574@defvr {NSIS} PACKAGE_NAME 575@code{PACKAGE_NAME} defines the name of the NSIS installer. In most 576cases this will be the same as the name of your project type. For 577instance, if you are creating a application, and have set 578@code{APP_NAME} to @samp{MyApplication}, Then set @code{PACKAGE_NAME} to 579the same thing, or just use @code{PACKAGE_NAME=$(APP_NAME)}. if 580@code{PACKAGE_NAME} is not set, it defaults to @code{unnamed-package} 581@end defvr 582 583@defvr {NSIS} PACKAGE_VERSION 584Set @code{PACKAGE_VERSION} to the release version number of your package. If not 585set, it defaults to 0.0.1 586@end defvr 587 588@defvr {NSIS} GNUSTEP_INSTALLATION_DOMAIN 589Set @code{GNUSTEP_INSTALLATION_DOMAIN} to the domain where you want to install 590the software. This should be either @code{SYSTEM}), @code{LOCAL}, or @code{USER}. 591If not set it defaults to @code{LOCAL}. 592@end defvr 593 594@node objc.make, palette.make, nsis.make, Project Types 595@subsection Objective-C Programs (@file{objc.make}) 596@menu 597* objc.make variables:: 598* Example ObjC Makefile:: 599@end menu 600 601The Makefile Package provides a project type that is useful for building 602Objective-C programs that do not depend upon the GNUstep libraries. 603Objective-C programs which only use the Objective-C Runtime Library and 604the classes it defines are candidates for this project type. 605 606@node objc.make variables, Example ObjC Makefile, objc.make, objc.make 607@subsubsection Project Variables 608 609Most of the project variables work the same as in Library 610projects (see @ref{library.make}). 611 612@defvr {Objective-C program project} OBJC_PROGRAM_NAME 613@code{OBJC_PROGRAM_NAME} is the list of names of Objective-C programs 614that are to be built; each name should be unique as it is the name of 615the executable file that will be generated. 616@end defvr 617 618@defvr {Objective-C program project} OBJC_LIBS 619@code{xxx_OBJC_LIBS} is the list of additional libraries that the linker 620will use when linking to create the @strong{xxx} Objective-C program 621executable file. These libraries are specific to the @strong{xxx} 622Objective-C program, see @ref{GNUmakefile.preamble,,ADDITIONAL_OBJC_LIBS}, 623to see how to specify additional global libraries. These libraries are 624placed before all of the Objective-C Runtime and system libraries, and 625before the global libraries specified with @code{ADDITIONAL_OBJC_LIBS}, 626so that they will be searched first when linking. The additional 627libraries should be specified as @samp{-l} flags to the linker as the 628following example illustrates. Replace the @strong{xxx} with the name 629of the program as listed by the @code{OBJC_PROGRAM_NAME} variable. 630@end defvr 631 632@node Example ObjC Makefile, , objc.make variables, objc.make 633@subsubsection Example Makefile 634 635This makefile illustrates two Objective-C programs, @file{simple} and 636@file{list} that are to be generated. 637 638@smallexample 639# 640# An example GNUmakefile 641# 642 643# Include the common variables defined by the Makefile Package 644include $(GNUSTEP_MAKEFILES)/common.make 645 646# Build a simple Objective-C program 647OBJC_PROGRAM_NAME = simple list 648 649# Have the Objective-C runtime macro be defined for simple program 650simple_CPPFLAGS = $(RUNTIME_DEFINE) 651 652# The Objective-C files to compile for simple program 653simple_OBJC_FILES = simple.m 654 655# The Objective-C files to compile for list program 656list_OBJC_FILES = list.m linkedlist.m 657 658# The C files to compile for list program 659list_C_FILES = sort.c 660 661# Option include to set any additional variables 662-include GNUmakefile.preamble 663 664# Include in the rules for making Objective-C programs 665include $(GNUSTEP_MAKEFILES)/objc.make 666 667# Option include to define any additional rules 668-include GNUmakefile.postamble 669@end smallexample 670 671The @file{simple} Objective-C program only consists of single 672Objective-C file; while, the @file{list} Objective-C program consists of 673two Objective-C files and one C file. The @file{simple} Objective-C 674program use the variable defined by the Makefile Package, 675@code{RUNTIME_DEFINE}, to define a macro based upon the Objective-C 676Runtime library; presumably @file{simple.m} has code which is dependent 677upon the Objective-C Runtime. 678 679@node palette.make, rpm.make, objc.make, Project Types 680@subsection Palettes (@file{palette.make}) 681 682A palette is a Bundle that provides some kind of GUI functionality. 683Otherwise it is similar to the Bundle project. 684 685@node rpm.make, service.make, palette.make, Project Types 686@subsection RPMs (@file{rpm.make}) 687 688The RPM project provides rules for automatically generating RPM spec 689files in order to make RPM distributions. Note that this project 690makefile is included automatically when you include any other project 691type in your GNUmakefile. It is non necessary to include 692@file{rpm.make}. 693 694Except for @code{PACKAGE_NAME}, which is required, all the following 695variables are optional. It is recommended that you set them anyway in 696order to provide the standard information that is present in most RPM 697distributions. 698 699@defvr {RPM} PACKAGE_NAME 700@code{PACKAGE_NAME} defines the name of the RPM distribution. In most 701cases this will be the same as the name of your project type. For 702instance, if you are creating a application, and have set 703@code{APP_NAME} to @samp{MyApplication}, Then set @code{PACKAGE_NAME} to 704the same thing, or just use @code{PACKAGE_NAME=$(APP_NAME)}. if 705@code{PACKAGE_NAME} is not set, it defaults to @code{unnamed-package} 706@end defvr 707 708@defvr {RPM} PACKAGE_VERSION 709Set @code{PACKAGE_VERSION} to the release version number of your package. If not 710set, it defaults to 0.0.1 711@end defvr 712 713@defvr {RPM} GNUSTEP_INSTALLATION_DOMAIN 714Set @code{GNUSTEP_INSTALLATION_DOMAIN} to the domain where you want to install 715the software. This should be either @code{SYSTEM}), @code{LOCAL}, or @code{USER}. 716If not set it defaults to @code{LOCAL}. 717@end defvr 718 719@defvr {RPM} PACKAGE_NEEDS_CONFIGURE 720Set this to @code{YES} if a configure script needs to be run before 721compilation 722@end defvr 723 724In addition you need to provide a stub spec file named for the package 725name, such as this example @file{libobjc.spec.in} file: 726 727@example 728Release: 1 729Source: ftp://ftp.gnustep.org/pub/gnustep/libs/%@{gs_name@}-%@{gs_version@}. 730tar.gz 731Copyright: GPL 732Group: Development/Libraries 733Summary: Objective-C Runtime Library 734Packager: Adam Fedor <fedor@@gnu.org> 735Vendor: The GNUstep Project 736URL: http://www.gnustep.org/ 737 738%description 739Library containing the Objective-C runtime. 740@end example 741 742@node service.make, subproject.make, rpm.make, Project Types 743@subsection Services (@file{service.make}) 744 745A Service is like a Tool that provides a service to a running GNUstep program. 746 747@node subproject.make, tool.make, service.make, Project Types 748@subsection Subprojects (@file{subproject.make}) 749 750A Subproject provides a way to organize code in a large application into 751subunits. The code in the subproject is merged in with the main tool 752or application. 753 754@node tool.make, , subproject.make, Project Types 755@subsection Command Line Tools (@file{tool.make}) 756 757A tool is an ObjC project that by default links in the GNUstep base 758library. Otherwise it is similar to the ObjC project type. 759 760@node GNUmakefile.preamble, GNUmakefile.postamble, Project Types, Top 761@section Global Variables (@file{GNUmakefile.preamble}) 762 763@file{GNUmakefile.preamble} is an optional file that may be put within the 764package for declaring global makefile variables for the package. The 765filename, @file{GNUmakefile.preamble}, is just a convention; likewise, the 766variables defined within it can be put in the normal @file{GNUmakefile} 767versus in this special file. However, the reason for this convention is 768that the @file{GNUmakefile} may be automatically maintained by a project 769management system, like Project Center, so any changes made to 770@file{GNUmakefile} may be discarded by that project management system. 771 772The file, @file{GNUmakefile.preamble}, in the Makefile Package is a 773template that can be used the project's @file{GNUmakefile.preamble}. It is 774not necessary to have a @file{GNUmakefile.preamble} with the project unless 775it is actually needed, the Makefile Package will only include it if it 776is available, see @ref{Makefile Structure} for information on how the 777Makefile Package includes a @file{GNUmakefile.preamble}. 778 779The rest of this section describes the individual global variables that 780the Makefile Package uses which are generally placed in the package's 781@file{GNUmakefile.preamble}. 782 783@defvar ADDITIONAL_CPPFLAGS 784@code{ADDITIONAL_CPPFLAGS} are additional flags that will be passed to 785the compiler preprocessor. Generally any macros to be defined for all 786files are placed here; the are passed for both Objective-C and C files 787that are compiled. @code{RUNTIME_DEFINE}, @code{FOUNDATION_DEFINE}, 788@code{GUI_DEFINE}, and @code{GUI_BACKEND_DEFINE} are some makefile 789variables which define macros that can be assigned to 790@code{ADDITIONAL_CPPFLAGS}. The following example illustrates the use 791of @code{ADDITIONAL_CPPFLAGS} to define a macro for the Objective-C 792Runtime Library plus an additional macro that is specific to the 793package. 794@end defvar 795 796@smallexample 797ADDITIONAL_CPPFLAGS = $(RUNTIME_DEFINE) -DVERBOSE=1 798@end smallexample 799 800@defvar ADDITIONAL_OBJCFLAGS 801@code{ADDITIONAL_OBJCFLAGS} are additional flags that will be passed to 802the compiler when compiling Objective-C files. Adding flags here does 803not override the default @code{OBJCFLAGS}, see @ref{Overridable 804Flags,,OBJCFLAGS}, they are in addition to @code{OBJCFLAGS}. Generally 805@code{ADDITIONAL_OBJCFLAGS} are placed before @code{OBJCFLAGS} when the 806compiler is executed, but one should avoid having any placement 807sensitive flags because the order of the flags is not guaranteed. The 808following example illustrates how you can pass additional Objective-C 809flags. 810@end defvar 811 812@smallexample 813ADDITIONAL_OBJCFLAGS = -Wno-protocol 814@end smallexample 815 816@defvar ADDITIONAL_CFLAGS 817@code{ADDITIONAL_CFLAGS} are additional flags that will be passed to the 818compiler when compiling C files. Adding flags here does not override 819the default @code{CFLAGS}, see @ref{Overridable Flags,,CFLAGS}, they are 820in addition to @code{CFLAGS}. Generally @code{ADDITIONAL_CFLAGS} are 821placed before @code{CFLAGS} when the compiler is executed, but one 822should avoid having any placement sensitive flags because the order of 823the flags is not guaranteed. The following example illustrates how you 824can pass additional C flags. 825@end defvar 826 827@smallexample 828ADDITIONAL_CFLAGS = -finline-functions 829@end smallexample 830 831@defvar ADDITIONAL_LDFLAGS 832@code{ADDITIONAL_LDFLAGS} are additional flags that will be passed to 833the linker when it creates an executable; these flags are passed when 834linking a command line tool, and application, or an Objective-C program. 835Adding flags here does not override the default @code{LDFLAGS}, see 836@ref{Overridable Flags,,LDFLAGS}, they are in addition to 837@code{LDFLAGS}. Generally @code{ADDITIONAL_LDFLAGS} are placed before 838@code{LDFLAGS} when the linker is executed, but one should avoid having 839any placement sensitive flags because the order of the flags is not 840guaranteed. The following example illustrates how you can pass addition 841linker flags. 842@end defvar 843 844@smallexample 845ADDITIONAL_LDFLAGS = -v 846@end smallexample 847 848@defvar ADDITIONAL_INCLUDE_DIRS 849@code{ADDITIONAL_INCLUDE_DIRS} is the list of additional directories that 850the compiler will search when it is looking for include files. The 851directories should be specified as @samp{-I} flags to the compiler. The 852additional include directories will be placed before the normal GNUstep 853and system include directories, so they will always be searched first. 854The following example illustrates two additional include directories; 855@code{/usr/local/gnu/include} will be searched first, then 856@code{/usr/gnu/include}, and finally the GNUstep and system directories 857which are automatically defined by the Makefile Package. 858@end defvar 859 860@smallexample 861ADDITIONAL_INCLUDE_DIRS = -I/usr/local/gnu/include -I/usr/gnu/include 862@end smallexample 863 864@defvar ADDITIONAL_LIB_DIRS 865@code{ADDITIONAL_LIB_DIRS} is the list of additional directories that 866the linker will search when it is looking for library files. The 867directories should be specified as @samp{-L} flags to the linker. The 868additional library directories will be placed before the GNUstep and 869system library directories so that they will be searched first by the 870linker. The following example illustrates two additional library 871directories; @code{/usr/local/gnu/lib} will be searched first, then 872@code{/usr/gnu/lib}, and finally the GNUstep and system directories 873which are automatically defined by the Makefile Package. 874@end defvar 875 876@smallexample 877ADDITIONAL_LIB_DIRS = -L/usr/local/gnu/lib -L/usr/gnu/lib 878@end smallexample 879 880@defvar ADDITIONAL_OBJC_LIBS 881@code{ADDITIONAL_OBJC_LIBS} is the list of additional libraries that the 882linker will use when linking command line tools, applications, and 883Objective-C programs, see @ref{tool.make}, @ref{application.make}, and 884@ref{objc.make}. For Objective-C programs, @code{ADDITIONAL_OBJC_LIBS} 885is placed before all of the Objective-C Runtime and system libraries so 886that they will be searched first when linking. For command line tools 887and applications, @code{ADDITIONAL_OBJC_LIBS} is placed @emph{before} 888all of the Objective-C Runtime and system libraries but @emph{after} the 889Foundation and GUI libraries. Libraries specified with 890@code{ADDITIONAL_OBJC_LIBS} should only depend upon the Objective-C 891Runtime and/or system functions, not Foundation or GUI classes; 892Foundation dependent libraries should be specified with 893@code{ADDITIONAL_TOOL_LIBS} and GUI dependent libraries should be 894specified with @code{ADDITONAL_GUI_LIBS}. The additional libraries 895should be specified as @samp{-l} flags to the linker as the following 896example illustrates. 897@end defvar 898 899@smallexample 900ADDITIONAL_OBJC_LIBS = -lSwarm 901@end smallexample 902 903@defvar ADDITIONAL_TOOL_LIBS 904@code{ADDITIONAL_TOOL_LIBS} is the list of additional libraries that the 905linker will use when linking command line tools and applications, see 906@ref{tool.make} and @ref{application.make}. For command line tools, 907@code{ADDITIONAL_TOOL_LIBS} is placed before all of the GNUstep and 908system libraries so that they will be searched first when linking. For 909applications, @code{ADDITIONAL_TOOL_LIBS} is placed before the 910Foundation and system libraries but after the GUI libraries. Libraries 911specified with @code{ADDITIONAL_TOOL_LIBS} should only depend upon the 912Foundation classes and/or system functions, not GUI classes; GUI 913dependent libraries should be specified with @code{ADDITIONAL_GUI_LIBS}. 914The additional libraries should be specified as @samp{-l} flags to the 915linker as the following example illustrates. 916@end defvar 917 918@smallexample 919ADDITIONAL_TOOL_LIBS = -lone -lsimple 920@end smallexample 921 922@defvar ADDITIONAL_GUI_LIBS 923@code{ADDITIONAL_GUI_LIBS} is the list of additional libraries that the 924linker will use when linking applications, see @ref{application.make}. 925@code{ADDITIONAL_GUI_LIBS} is placed before all of the GUI, Foundation, 926and system libraries so that they will be searched first when linking. 927The additional libraries should be specified as @samp{-l} flags to the 928linker as the following example illustrates. 929@end defvar 930 931@smallexample 932ADDITIONAL_GUI_LIBS = -lMiscGui 933@end smallexample 934 935@defvar ADDITIONAL_INSTALL_DIRS 936@code{ADDITIONAL_INSTALL_DIRS} is the list of additional directories 937that should be created when the Makefile Package installs the file for 938the project. These directories are only one that the project needs to 939be created but that the Makefile Package does not automatically 940create. The directories should be absolute paths but use the 941@code{GNUSTEP_LIBRARY} variable and other Makefile Package define 942variables, see @ref{Directory Paths}, so that the directories get 943created in the appropriate place relative to the other file installed 944for the project. The following example illustrates how two additional 945directories can be created during installation. 946@end defvar 947 948@smallexample 949ADDITIONAL_INSTALL_DIRS = $(GNUSTEP_RESOURCES)/MyProject 950@end smallexample 951 952@defvar LIBRARIES_DEPEND_UPON 953@code{LIBRARIES_DEPEND_UPON} is the set of libraries that the shared 954library depends upon, see @ref{library.make} for more information about 955building shared libraries; this variable is only relevant for library 956project types. On some platforms when a shared library is built, any 957libraries which the object code in the shared library depends upon must 958be linked in the generation of the shared library. This is similar to 959the process of linking an executable file like a command line tool or 960Objective-C program except that the result is a shared library. 961Libraries specified with @code{LIBRARIES_DEPEND_UPON} should be listed 962as @samp{-l} flags to the linker; when possible use variables defined by 963the Makefile Package to specify GUI, Foundation, or system libraries; 964like @code{GUI_LIBS}, @code{FND_LIBS}, @code{OBJC_LIBS}, or 965@code{SYSTEM_LIBS}. @code{LIBRARIES_DEPEND_UPON} is independent of 966@code{ADDITIONAL_OBJC_LIBS}, @code{ADDITIONAL_TOOL_LIBS}, and 967@code{ADDITIONAL_GUI_LIBS}, so any libraries specified there may need to 968be specified with @code{LIBRARIES_DEPEND_UPON}. The following example 969illustrates the use of @code{LIBRARIES_DEPEND_UPON} for a shared library 970that is depend upon the Foundation, ObjC, system libraries and an 971additional user library. 972@end defvar 973 974@smallexample 975LIBRARIES_DEPEND_UPON = -lsimple $(FND_LIBS) $(OBJC_LIBS) $(SYSTEM_LIBS) 976@end smallexample 977 978 979@node GNUmakefile.postamble, Common Variables, GNUmakefile.preamble, Top 980@section Global Rules (@file{GNUmakefile.postamble}) 981 982The @file{GNUmakefile.postamble} file is an optional file you may 983include in your package to define additional rules that should be 984executed when making and/or installing the project. There is a template 985@file{GNUmakefile.postamble} file in the Makefile package that you can 986use as an example. Most of the rules are self explanatory. The 987@samp{before-} rules define things that should happen before a process 988is executed (e.g. @samp{before-all} for before compilation, 989@samp{before-install} for before installation). The @samp{after-} rules 990define things that should happen after a process is complete. 991 992You can even define additional rules such as ones that a particular to 993your specific package or that are to be used by developers only. 994 995@node Common Variables, Other Variables, GNUmakefile.postamble, Top 996@section Common Variables (@file{common.make}) 997@menu 998* Directory Paths:: 999* Scripts:: 1000* Platform Information:: 1001* Library Combination:: 1002* Overridable Flags:: 1003@end menu 1004 1005Any of these variables that are defined by @file{common.make} can and 1006should be used by the user's makefile fragments to reference directories 1007and/or perform any tasks which are not done automatically by the 1008Makefile Package. Most variables refer to directory paths, both 1009absolute and relative, where files will be installed, but other 1010variables are defined based upon the target platform that the person is 1011compiling for. Do not change the values of any of these automatically 1012defined variables as the resultant behaviour of the Makefile Package is 1013undefined. 1014 1015@node Directory Paths, Scripts, Common Variables, Common Variables 1016@subsection Directory Paths 1017 1018@defvar GNUSTEP_MAKEFILES 1019@code{GNUSTEP_MAKEFILES} is the absolute path to the directory where the 1020Makefile Package files are located. Use @code{GNUSTEP_MAKEFILES} to 1021refer to a makefile fragment or script file from the Makefile Package 1022within a makefile; the @code{GNUSTEP_MAKEFILES} variable should be 1023only be used within makefiles and not referenced within C or Objective-C 1024programs. 1025@end defvar 1026 1027@defvar GNUSTEP_APPS 1028@code{GNUSTEP_APPS} is the absolute path to the directory where GUI 1029applications are installed. This variable is dependent upon the 1030@code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will change 1031accordingly if the user specifies a different installation domain. 1032@end defvar 1033 1034@defvar GNUSTEP_ADMIN_APPS 1035@code{GNUSTEP_ADMIN_APPS} is the absolute path to the directory where 1036GUI applications for the system Administrator are installed. This 1037variable is dependent upon the @code{GNUSTEP_INSTALLATION_DOMAIN} 1038variable, so the path will change accordingly if the user specifies a 1039different installation domain. 1040@end defvar 1041 1042@defvar GNUSTEP_WEB_APPS 1043@code{GNUSTEP_WEB_APPS} is the absolute path to the directory where 1044web applications (for web development frameworks such as GSWeb or 1045SOPE) are installed. This variable is dependent upon the 1046@code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will change 1047accordingly if the user specifies a different installation domain. 1048@end defvar 1049 1050@defvar GNUSTEP_TOOLS 1051@code{GNUSTEP_TOOLS} is the absolute path for the root directory where 1052command line tools are installed. Only command line tools which are 1053target platform independent should be installed in @code{GNUSTEP_TOOLS}; 1054target platform dependent command line tools should be placed in the 1055appropriate subdirectory of @code{GNUSTEP_TOOLS}, see @ref{Directory 1056Paths,,GNUSTEP_TARGET_DIR}, and @ref{Directory 1057Paths,,TOOL_INSTALLATION_DIR}. This variable is dependent upon the 1058@code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will change 1059accordingly if the user specifies a different installation domain. 1060@end defvar 1061 1062@defvar GNUSTEP_ADMIN_TOOLS 1063@code{GNUSTEP_ADMIN_TOOLS} is the absolute path for the root directory 1064where command line tools for the system administrator are installed. 1065Only command line tools which are target platform independent should 1066be installed in @code{GNUSTEP_ADMIN_TOOLS}; target platform dependent 1067command line tools should be placed in the appropriate subdirectory of 1068@code{GNUSTEP_ADMIN)TOOLS}, see @ref{Directory 1069Paths,,GNUSTEP_TARGET_DIR}, and @ref{Directory 1070Paths,,TOOL_INSTALLATION_DIR}. This variable is dependent upon the 1071@code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will change 1072accordingly if the user specifies a different installation domain. 1073@end defvar 1074 1075@defvar GNUSTEP_HEADERS 1076@code{GNUSTEP_HEADERS} is the absolute path for the root directory where 1077header files are installed. Normally header files are not installed in 1078the @code{GNUSTEP_HEADERS} directory, but in a subdirectory as specified 1079by the project which owns the files, see @ref{library.make} for more 1080information. @code{GNUSTEP_HEADERS} should contain platform independent 1081header files because the files are shared by all platforms. Any target 1082platform dependent header files should be placed in the appropriate 1083subdirectory as specified by @code{GNUSTEP_TARGET_DIR}. This variable 1084is dependent upon the @code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the 1085path will change accordingly if the user specifies a different 1086installation domain. 1087@end defvar 1088 1089@defvar GNUSTEP_LIBRARY 1090@code{GNUSTEP_LIBRARY} is the absolute path for the 'Library' 1091directory where all sorts of resources are installed. This directory 1092can be expected to have (at least) some standard subdirectories with 1093fixed names, which are @code{ApplicationSupport}, @code{Bundles}, 1094@code{Frameworks}, @code{ApplicationSupport/Palettes}, 1095@code{Services}, @code{Libraries/Resources} and @code{Libraries/Java}. 1096You can access them in your GNUmakefile as 1097@code{GNUSTEP_LIBRARY/ApplicationSupport}, 1098@code{GNUSTEP_LIBRARY/Bundles}, etc. This variable is dependent upon 1099the @code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will 1100change accordingly if the user specifies a different installation 1101domain. 1102@end defvar 1103 1104@defvar GNUSTEP_LIBRARIES 1105@code{GNUSTEP_LIBRARIES} is the absolute path for the directory where 1106libraries are installed taking the target platform and library 1107combination into account. This directory is generally where library 1108project types, see @ref{library.make}, will install the library file. 1109This variable is dependent upon the @code{GNUSTEP_INSTALLATION_DOMAIN} 1110variable, so the path will change accordingly if the user specifies a 1111different installation domain. 1112@end defvar 1113 1114@defvar GNUSTEP_RESOURCES 1115@code{GNUSTEP_RESOURCES} is the absolute path for the directory where 1116resource files for libraries are installed; example resources are 1117fonts, printer type information, model files for system panels, and 1118system images. The resource files are generally associated with 1119libraries, because resources for applications or bundles are included 1120within the application or bundle directory wrapper. 1121@code{GNUSTEP_RESOURCES} is the @code{Libraries/Resources} 1122subdirectory of @code{GNUSTEP_LIBRARY}; it is dependent upon the 1123@code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will change 1124accordingly if the user specifies a different installation domain. 1125@end defvar 1126 1127@defvar GNUSTEP_DOC 1128@code{GNUSTEP_DOC} is the absolute path for the directory where 1129documentation is installed (with the exception of man pages and info 1130documentation, which need to be installed into @code{GNUSTEP_DOC_MAN} 1131and @code{GNUSTEP_DOC_INFO}). This variable is dependent upon the 1132@code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will change 1133accordingly if the user specifies a different installation domain. 1134@end defvar 1135 1136@defvar GNUSTEP_DOC_MAN 1137@code{GNUSTEP_DOC_MAN} is the absolute path for the directory where 1138man pages are to be installed. This variable is dependent upon the 1139@code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will change 1140accordingly if the user specifies a different installation domain. 1141@end defvar 1142 1143@defvar GNUSTEP_DOC_INFO 1144@code{GNUSTEP_DOC_INFO} is the absolute path for the directory where 1145info documentation is installed. This variable is dependent upon the 1146@code{GNUSTEP_INSTALLATION_DOMAIN} variable, so the path will change 1147accordingly if the user specifies a different installation domain. 1148@end defvar 1149 1150@defvar GNUSTEP_HOST_DIR 1151@code{GNUSTEP_HOST_DIR} is the subdirectory path for the host platform 1152CPU and operating system. It is a composed from the 1153@code{GNUSTEP_HOST_CPU} and @code{GNUSTEP_HOST_OS} variables. 1154@end defvar 1155 1156@defvar GNUSTEP_TARGET_DIR 1157@code{GNUSTEP_TARGET_DIR} is the subdirectory path for the target 1158platform CPU and operating system. It is composed from the 1159@code{GNUSTEP_TARGET_CPU} and @code{GNUSTEP_TARGET_OS} variables. 1160@code{GNUSTEP_TARGET_DIR} is generally used as part of the 1161installation path when platform specific files are installed. 1162@end defvar 1163 1164@defvar GNUSTEP_OBJ_DIR 1165@code{GNUSTEP_OBJ_DIR} is the subdirectory path where the Makefile 1166Package places binary files: object files, libraries, executables, 1167produced by the compiler. The Makefile Package separates binary files 1168for different target platforms, different library combinations, and 1169different compile options into different directories; these different 1170directories are subdirectories from the current directory where the 1171makefile resides. This structure allows a package to be compiled for 1172different target platforms, different library combinations, and 1173different compile options @emph{in place}; i.e. the binary files are 1174separated from each other so a compile pass from one set of options do 1175not overwrite or erase binary files from a previous compile pass with 1176different options. Generally the user does not use this variable; 1177however, if the package needs to manually install some binary files 1178than the makefile fragment uses this variable to reference the path 1179where the binary file is located. 1180@end defvar 1181 1182@node Scripts, Platform Information, Directory Paths, Common Variables 1183@subsection Scripts 1184 1185@defvar CONFIG_GUESS_SCRIPT 1186@code{CONFIG_GUESS_SCRIPT} is the absolute path to the 1187@file{config.guess} script within the Makefile Package; this script is 1188used to determine host and target platform information. The Makefile 1189Package executes this script to determine the values of the host 1190platform variables: @code{GNUSTEP_HOST}, @code{GNUSTEP_HOST_CPU}, 1191@code{GNUSTEP_HOST_VENDOR}, @code{GNUSTEP_HOST_OS}, and the target 1192platform variables: @code{GNUSTEP_TARGET}, @code{GNUSTEP_TARGET_CPU}, 1193@code{GNUSTEP_TARGET_VENDOR}, @code{GNUSTEP_TARGET_OS}; generally the 1194user does not need to execute this script because the Makefile Package 1195executes it automatically. 1196@end defvar 1197 1198@defvar CONFIG_SUB_SCRIPT 1199@code{CONFIG_SUB_SCRIPT} is the absolute path to the @file{config.sub} 1200script within the Makefile Package; this script takes a platform name 1201and canonicalizes it, i.e. it puts the name in a standard form. The 1202Makefile Package uses this script when the user specifies a target 1203platform for compilation; the target platform name is canonicalized so 1204that the Makefile Package can properly parse the name into its 1205different components. Generally the user does not execute this 1206script. 1207@end defvar 1208 1209@defvar CONFIG_CPU_SCRIPT 1210@code{CONFIG_CPU_SCRIPT} is the absolute path to the @file{cpu.sh} 1211script within the Makefile Package; this script extracts the CPU name 1212from a canonicalized platform name. Generally the user does not 1213execute this script; it is used internally by the Makefile Package. 1214@end defvar 1215 1216@defvar CONFIG_VENDOR_SCRIPT 1217@code{CONFIG_VENDOR_SCRIPT} is the absolute path to the 1218@file{vendor.sh} script within the Makefile Package; this script 1219extracts the vendor name from a canonicalized platform name. 1220Generally the user does not execute this script; it is used internally 1221by the Makefile Package. 1222@end defvar 1223 1224@defvar CONFIG_OS_SCRIPT 1225@code{CONFIG_OS_SCRIPT} is the absolute path to the @file{os.sh} 1226script within the Makefile Package; this script extracts the operating 1227system name from a canonicalized platform name. Generally the user 1228does not execute this script; it is used internally by the Makefile 1229Package. 1230@end defvar 1231 1232@defvar CLEAN_CPU_SCRIPT 1233@code{CLEAN_CPU_SCRIPT} is the absolute path to the 1234@file{clean_cpu.sh} script within the Makefile Package; this script 1235takes a platform CPU name and @emph{cleans} it for use by the Makefile 1236Package. The process of cleaning refers to the situation where 1237numerous equivalent processors, which have different names, are mapped 1238to a single name. For example, the Intel line of processors: i386, 1239i486, Pentium, all have different CPU names, but the Makefile Package 1240considers them equivalent and cleans those names so that the single 1241name @file{ix86} is used. Generally the user does not execute this 1242script; it is used internally by the Makefile Package. 1243@end defvar 1244 1245@defvar CLEAN_VENDOR_SCRIPT 1246@code{CLEAN_VENDOR_SCRIPT} is the absolute path to the 1247@file{clean_vendor.sh} script within the Makefile Package; this script 1248takes a platform vendor name and @emph{cleans} it for use by the 1249Makefile Package. The process of cleaning refers to the situation 1250where numerous equivalent vendors, which have different names, are 1251mapped to a single name. Generally the user does not execute this 1252script; it is used internally by the Makefile Package. 1253@end defvar 1254 1255@defvar CLEAN_OS_SCRIPT 1256@code{CLEAN_OS_SCRIPT} is the absolute path to the @file{clean_os.sh} 1257script within the Makefile Package; this script takes a platform 1258operating system name and @emph{cleans} it for use by the Makefile 1259Package. The process of cleaning refers to the situation where 1260numerous equivalent operating systems, which have different names, are 1261mapped to a single name. Generally the user does not execute this 1262script; it is used internally by the Makefile Package. 1263@end defvar 1264 1265@node Platform Information, Library Combination, Scripts, Common Variables 1266@subsection Host and Target Platform Information 1267 1268@defvar GNUSTEP_HOST 1269@code{GNUSTEP_HOST} is the canonical host platform name; i.e. the name 1270of the platform which is performing compilation of programs. For 1271example, a SPARC machine by Sun Microsystems running the Solaris 2.5.1 1272operating system has the name @code{sparc-sun-solaris2.5.1}. 1273@end defvar 1274 1275@defvar GNUSTEP_HOST_CPU 1276@code{GNUSTEP_HOST_CPU} is the CPU name for the canonical host 1277platform name; i.e. the name of the CPU platform which is performing 1278compilation of programs. The Makefile Package cleans this CPU name 1279with the @code{CLEAN_CPU_SCRIPT} script before using it internally. 1280For example, the canonical host platform name of 1281@code{i586-pc-linux-gnu} has a CPU name of @code{ix86}. 1282@end defvar 1283 1284@defvar GNUSTEP_HOST_VENDOR 1285@code{GNUSTEP_HOST_VENDOR} is the vendor name for the canonical host 1286platform; i.e. the name of the vendor platform which is performing 1287compilation of programs. The Makefile Package cleans this vendor name 1288with the @code{CLEAN_VENDOR_SCRIPT} script before using it internally. 1289For example, the canonical host platform name of 1290@code{sparc-sun-solaris2.5.1} has a vendor name of @code{sun}. 1291@end defvar 1292 1293@defvar GNUSTEP_HOST_OS 1294@code{GNUSTEP_HOST_OS} is the operating system name for the canonical 1295host platform; i.e. the name of the operating system platform which is 1296performing compilation of programs. The Makefile Package cleans this 1297operating system name with the @code{CLEAN_OS_SCRIPT} script before 1298using it internally. For example, the canonical host platform name of 1299@code{i586-pc-linux-gnu} has an operating system name of 1300@code{linux-gnu}. 1301@end defvar 1302 1303@defvar GNUSTEP_TARGET 1304@code{GNUSTEP_TARGET} is the canonical target platform name; 1305i.e. compilation of programs generate object code for this platform. 1306By default the target platform is the same as the host platform unless 1307the user specifies a different target when running make, see Cross 1308Compiling. 1309@end defvar 1310 1311@defvar GNUSTEP_TARGET_CPU 1312@code{GNUSTEP_TARGET_CPU} is the CPU name for the canonical target 1313platform; i.e. compilation of programs generate object code for this 1314CPU platform. The Makefile Package cleans this operating system name 1315with the @code{CLEAN_CPU_SCRIPT} script before using it internally. 1316By default the target CPU platform is the same as the host CPU 1317platform, @code{GNUSTEP_HOST_CPU}, unless the user specifies a 1318different target platform when running make, see Cross Compiling. 1319@end defvar 1320 1321@defvar GNUSTEP_TARGET_VENDOR 1322@code{GNUSTEP_TARGET_VENDOR} is the vendor name for the canonical 1323target platform; i.e. compilation of programs generate object code for 1324this vendor platform. The Makefile Package cleans this vendor name 1325with the @code{CLEAN_VENDOR_SCRIPT} script before using it internally. 1326By default the target vendor platform is the same as the host vendor 1327platform, @code{GNUSTEP_HOST_VENDOR}, unless the user specifies a 1328different target platform when running make, see Cross Compiling. 1329@end defvar 1330 1331@defvar GNUSTEP_TARGET_OS 1332@code{GNUSTEP_TARGET_OS} is the operating system name for the 1333canonical target platform; i.e. compilation of programs generate 1334object code for this operating system platform. The Makefile Package 1335cleans this operating system name with the @code{CLEAN_OS_SCRIPT} 1336script before using it internally. By default the target operating 1337system platform is the same as the host operating system platform, 1338@code{GNUSTEP_HOST_OS}, unless the user specifies a different target 1339platform, see Cross Compiling. 1340@end defvar 1341 1342@node Library Combination, Overridable Flags, Platform Information, Common Variables 1343@subsection Library Combination 1344 1345@defvar OBJC_RUNTIME_LIB 1346@code{OBJC_RUNTIME_LIB} is assigned the code that indicates the 1347Objective-C Runtime library which compiled Objective-C programs will 1348use; the four possible values are: @samp{ng} for the GNUstep Runtime 1349with latest language features turned on at acompile time, @samp{gnu} 1350for the GNU Runtime (or the GNUstep runtime with traditional 1351language features compiled), @samp{nx} for the NeXT Runtime, 1352and @samp{sun} for the Sun Microsystems Runtime. 1353The Objective-C Runtime library can be changed 1354to use a library other than the default with the @samp{library_combo} 1355make parameter, see @ref{Running Make} for more details. Read 1356@ref{Library Combination} for more information on how the Makefile 1357Package handles different library combinations. If a makefile must 1358perform specific operations dependent upon the Objective-C Runtime 1359library then this variable is the one to check. 1360@end defvar 1361 1362@defvar RUNTIME_VERSION 1363@code{RUNTIME_VERSION} is set to and allows you to override the Objective-C 1364runtime ABI in use by the clang compiler. Generally, gnustep-make will provide 1365a sane default for you.Please be aware that mixing different ABIs in the same 1366binary is not generally supported. Possible values: 1367 1368@table @samp 1369@item gcc 1370This is the classic ABI also implemented by GCC which does not support advanced 1371features such as ARC or non-fragile instance variables. 1372 1373@item gnustep-1.8 1374This is the first iteration of the GNUstep Objective-C ABI, which supports the 1375advanced features while remaining compatible with the GCC ABI. Requires the 1376GNUstep Objective-C runtime (libobjc2) 1.8 or later. 1377 1378@item gnustep-2.0 1379This version breaks compatibility with the older runtime ABIs in order to 1380provide better introspection metadata, reduced memory usage and smaller 1381binaries. Requires the GNUstep Objective-C runtime (libobjc2) 2.0 or later. 1382@end table 1383@end defvar 1384 1385@defvar RUNTIME_DEFINE 1386@code{RUNTIME_DEFINE} is assigned a preprocessor flag that can be 1387passed to the compiler which defines a macro based upon the 1388Objective-C Runtime library that compiled Objective-C programs will 1389use. This macro is useful if the compiled program must execute 1390different code based upon the Objective-C Runtime being used. See 1391@ref{GNUmakefile.preamble} for an example on how to pass this 1392preprocessor flag when compiling. The four possible values are: 1393@samp{-DGNUSTEP_RUNTIME=1} for the GNUstep ObjectiveC-2 Runtime, 1394@samp{-DGNU_RUNTIME=1} for the GNU Runtime, @samp{-DNeXT_RUNTIME=1} 1395for the NeXT Runtime, and @samp{-DSun_RUNTIME=1} for the Sun 1396Microsystems Runtime. 1397@end defvar 1398 1399@defvar FOUNDATION_LIB 1400@code{FOUNDATION_LIB} is assigned the code that indicates the 1401Foundation Kit library, as specified by the OpenStep specification, 1402which compiled Objective-C programs will use; the four possible values 1403are: @samp{gnu} for the GNUstep Base Library, @samp{nx} for the NeXT 1404Foundation Kit Library, @samp{sun} for the Sun Microsystems Foundation 1405Kit Library, and @samp{fd} for the libFoundation Library. The 1406Foundation Kit library can be changed to use a library other than the 1407default with the @samp{library_combo} make parameter, see @ref{Running 1408Make} for more details. Read @ref{Library Combination} for more 1409information on how the Makefile Package handles different library 1410combinations. If a makefile must perform specific operations 1411dependent upon the Foundation Kit library then this variable is the 1412one to check. 1413@end defvar 1414 1415@defvar FND_DEFINE 1416@code{FND_DEFINE} is assigned a preprocessor flag that can be passed 1417to the compiler which defines a macro based upon the Foundation Kit 1418library, as specified by the OpenStep specification, which compiled 1419Objective-C programs will use. This macro is useful if the compiled 1420program must execute different code based upon the Foundation Kit 1421library being used. See @ref{GNUmakefile.preamble} for an example on 1422how to pass this preprocessor flag when compiling. The four possible 1423values are: @samp{-DGNUSTEP_BASE_LIBRARY=1} for the GNUstep Base 1424Library, @samp{-DNeXT_Foundation_LIBRARY=1} for the NeXT Foundation 1425Kit Library, @samp{-DSun_Foundation_LIBRARY=1} for the Sun 1426Microsystems Foundation Kit Library, and 1427@samp{-DLIB_FOUNDATION_LIBRARY=1} for the libFoundation Library. 1428@end defvar 1429 1430@defvar GUI_LIB 1431@code{GUI_LIB} is assigned the code that indicates the Application Kit 1432library, as specified by the OpenStep specification, which compiled 1433Objective-C programs will use; the two possible values are: @samp{gnu} 1434for the GNUstep GUI Library and @samp{nx} for the NeXT Application Kit 1435Library. The Application Kit library can be changed to use a library 1436other than the default with the @samp{library_combo} make parameter, 1437see @ref{Running Make} for more details. Read @ref{Library 1438Combination} for more information on how the Makefile Package handles 1439different library combinations. If a makefile must perform specific 1440operations dependent upon the Application Kit library then this 1441variable is the one to check. 1442@end defvar 1443 1444@defvar GUI_DEFINE 1445@code{GUI_DEFINE} is assigned a preprocessor flag that can be passed 1446to the compiler which defines a macro based upon the Application Kit 1447library, as specified by the OpenStep specification, which compiled 1448Objective-C programs will use. This macro is useful if the compiled 1449program must execute different code based upon the Application Kit 1450library being used. See @ref{GNUmakefile.preamble} for an example on 1451how to pass this preprocessor flag when compiling. The two possible 1452values are: @samp{-DGNUSTEP_GUI_LIBRARY=1} for the GNUstep GUI Library 1453and @samp{-DNeXT_Application_LIBRARY=1} for the NeXT Application Kit 1454Library. 1455@end defvar 1456 1457@defvar GUI_BACKEND_LIB 1458@code{GUI_BACKEND_LIB} is assigned the code that indicates the backend 1459library which compiled Objective-C programs will use in conjunction 1460with the GNUstep GUI Library. The three possible values are: 1461@samp{xdps} for the GNUstep X/DPS GUI Backend Library, @samp{nsx} for 1462the NSKit GUI Backend Library, and @samp{w32} for the MediaBook WIN32 1463GUI Backend Library. @code{GUI_BACKEND_LIB} is only relevant when 1464@code{GUI_LIB} is set to @samp{gnu}; otherwise, @code{GUI_BACKEND_LIB} 1465will be set to @samp{nil} to indicate that there is no backend 1466library. @code{GUI_BACKEND_LIB} can be changed to use a library other 1467than the default with the @samp{library_combo} make parameter, see 1468@ref{Running Make} for more details. Read @ref{Library Combination} 1469for more information on how the Makefile Package handles different 1470library combinations. If a makefile must perform specific operations 1471dependent upon the backend library then this variable is the one to 1472check. 1473@end defvar 1474 1475@defvar GUI_BACKEND_DEFINE 1476@code{GUI_BACKEND_DEFINE} is assigned a preprocessor flag that can be 1477passed to the compiler which defines a macro based upon the backend 1478library which compiled Objective-C programs will use in conjunction 1479with the GNUstep GUI Library. This macro is useful if the compiled 1480program must execute different code based upon the backend library 1481being used. See @ref{GNUmakefile.preamble} for an example on how to 1482pass this preprocessor flag when compiling. The three possible values 1483are: @samp{-DXDPS_BACKEND_LIBRARY=1} for the GNUstep X/DPS GUI Backend 1484Library, @samp{-DNSX_BACKEND_LIBRARY=1} for the NSKit GUI Backend 1485Library, and @samp{-DW32_BACKEND_LIBRARY=1} for the MediaBook WIN32 1486GUI Backend Library. @code{GUI_BACKEND_DEFINE} is not defined if 1487there is not backend library; i.e. @code{GUI_BACKEND_LIB} is 1488@samp{nil}. 1489@end defvar 1490 1491@node Overridable Flags, , Library Combination, Common Variables 1492@subsection Overridable Flags 1493 1494@defvar OBJCFLAGS 1495@code{OBJCFLAGS} are flags that are passed to the compiler when 1496compiling Objective-C files. The user can override this variable when 1497running make and specify different flags as the following command 1498illustrates: 1499@end defvar 1500 1501@smallexample 1502make OBJCFLAGS="-Wno-implicit -Wno-protocol" 1503@end smallexample 1504 1505@defvar CFLAGS 1506@code{CFLAGS} are flags that are passed to the compiler when compiling 1507C files. The user can override this variable when running make and 1508specify different flags as the following command illustrates: 1509@end defvar 1510 1511@smallexample 1512make CFLAGS="-Wall" 1513@end smallexample 1514 1515@defvar OPTFLAG 1516@code{OPTFLAG} is the flag used to indicate the optimization level 1517that the compiler should perform when compiling Objective-C and C 1518files; this flag is set to @samp{-O2} by default, but the user can 1519override this setting when running make as the following command 1520illustrates: 1521@end defvar 1522 1523@smallexample 1524make OPTFLAG= 1525@end smallexample 1526 1527This command sets the optimization flag to be empty so that no 1528optimization will be performed by the compiler. 1529 1530@defvar GNUSTEP_INSTALLATION_DOMAIN 1531@code{GNUSTEP_INSTALLATION_DOMAIN} is the domain where the package 1532will install its files; overriding this variable when running make 1533will change all of the variables within the Makefile Package that 1534depend upon it; the following command illustrates the use of this 1535variable: 1536@end defvar 1537 1538@smallexample 1539make GNUSTEP_INSTALLATION_DOMAIN=SYSTEM 1540@end smallexample 1541 1542This command states that the @code{SYSTEM} domain should be used as 1543the installation root directory; in particular applications in the 1544package will be installed in the @file{$GNUSTEP_SYSTEM_APPS} 1545directory, libraries in the package will be installed under the 1546@file{$GNUSTEP_SYSTEM_LIBRARIES} directory, command line tools will be 1547installed under the @file{$GNUSTEP_SYSTEM_TOOLS} directory, etc. 1548Depending on the filesystem layout, the various directories may be 1549located anywhere, which is why it's important to also refer to them by 1550using variables such as @code{GNUSTEP_APPS}, @code{GNUSTEP_LIBRARIES} 1551and @code{GNUSTEP_TOOLS}, which automatically point to the right 1552directory on disk for this filesystem layout and installation domain. 1553 1554By default the Makefile Package sets 1555@code{GNUSTEP_INSTALLATION_DOMAIN} to @code{LOCAL}. 1556 1557@defvar messages 1558@code{messages} can be set to @samp{yes} in order to increase the 1559verbosity and see all the commands the make is executing. 1560@end defvar 1561 1562@smallexample 1563make messages=yes 1564@end smallexample 1565 1566@defvar documentation 1567@code{documentation} controls whether the documentation targets in 1568a project will be executed. If you don't desire building the 1569documentation (which might require a working LaTeX installation, etc.) 1570you can set this to @samp{no}. Otherwise the documentation will 1571be built. 1572@end defvar 1573 1574@smallexample 1575make documentation=no 1576@end smallexample 1577 1578@node Other Variables, , Common Variables, Top 1579@section Other Variables 1580 1581Since gnustep-make is a system of scripts rather than compiled code, 1582all the source is always present and available to read, so the main 1583documentation is intentionally provided as comments within that source. 1584 1585In particular, gnustep-make variables are documented at the head of the 1586project-type files in which they are used. 1587eg $GNUSTEP_MAKEFILES/Instance/library.make for the variables 1588used to build a library. 1589 1590However, there are some variables which, while not in provided in 1591@file{common.make} are of more general use, and therefore may reasonably 1592be documented here: 1593 1594@defvar GS_WITH_ARC 1595@code{GS_WITH_ARC} may be set to 1 to turns on ARC for the current build if using the Next Generation runtime setting. This variable may be defined as an environment variable, or on the make command line, or (usually) in the GNUmakefile. The library-combo needs to specify the next generation runtime (eg ng-gnu-gnu) for this variable to take effect. When the ng runtme is used, setting this variable causes the the flags specified in ARC_OBJCFLAGS to be used when compiling any Objective-C source files). If no value is defined for @code{ARC_OBJCFLAGS} it is assumed to be '-fobjc-arc -fobjc-arc-exceptions' so that code is built with ARC enabled and with support for exceptions (objects are not leaked when an exception occurs). Alternatively, to switch on ARC for individual files, you can have a makefile fragment like this: 1596@end defvar 1597@smallexample 1598ifeq ($(OBJC_RUNTIME_LIB), ng) 1599file1.m_FILE_FLAGS+="-fobjc-arc -fobjc-arc-exceptions" 1600file2.m_FILE_FLAGS+="-fobjc-arc -fobjc-arc-exceptions" 1601file9.m_FILE_FLAGS+="-fobjc-arc -fobjc-arc-exceptions" 1602endif 1603@end smallexample 1604 1605@defvar ARC_CPPFLAGS 1606@code{ARC_CPPFLAGS} sets the flags to defien preprocessor values be used when building code for ARC. This variable is used only if ng runtime is used and the @code{GS_WITH_ARC} variable is set to say that ARC is used. 1607@end defvar 1608 1609@defvar ARC_OBJCFLAGS 1610@code{ARC_OBJCFLAGS} sets the compiler/linker flags to be used when building code for ARC. This variable is used only if ng runtime is used and the 'GS_WITH_ARC' variable is set to say that ARC is used. The -fobjc-arc flag enables ARC, but by default ARC_OBJCFLAGS is assumed to be -fobjc-arc -fobjc-arc-exceptions, which adds support for exceptions (reducing performance, but preventing leaked memory when an exception occurs). 1611@end defvar 1612 1613@defvar xxx_FILE_FILTER_OUT_FLAGS 1614@code{xxx_FILE_FILTER_OUT_FLAGS} (where xxx is the file name, such as mframe.m) 1615is a filter-out make pattern of flags to be filtered out 1616from the compilation flags when compiling xxx. 1617In exceptional conditions, you might need to want to use different compiler 1618flags for a file (for example, if a file doesn't compile with optimization 1619turned on, you might want to compile that single file with optimizations 1620turned off). 1621@end defvar 1622@smallexample 1623file.m_FILE_FILTER_OUT_FLAGS = -O% -fomit-frame-pointer 1624@end smallexample 1625This says that when compiling file.m we should disable optimization flags, 1626and also remove frame pointer information. 1627 1628@defvar xxx_FILE_FLAGS 1629@code{xxx_FILE_FLAGS} (where xxx is the file name, such as main.m) 1630add special compilation flags to be used when compiling xxx. 1631In exceptional conditions, you might need to want to use different compiler 1632flags for a file (for example, if ou want to turn on automated reference 1633counting for that file) 1634@end defvar 1635@smallexample 1636file.m_FILE_FLAGS = -fobjc-arc 1637@end smallexample 1638This says that when compiling file.m we should turn on ARC. 1639 1640@bye 1641