P L A T F O R M C O N F I G U R A T O R FILE FORMAT SPECIFICATION ABOUT ----- This file describes the format of the Platform Configurator's (pconf) platform configuration file format (platforms.ini). LEGEND ------ Comments start with a '#' character. Any '#' character found within a value or parameter will be interprited as part of that value or parameter (not interprited as a comment). Parameters may be intended with initial tabs or spaces. Values always start after the '=' character which is always following a parameter, ie: PREFIX = /usr/ If a value runs long, then do not put " around it. Instead use backslashes to escape as " characters are read literally, example: Description = The quick red foxes jumped over the "lazy" \ brown dog. PARAMETERS: GLOBAL ------------------ These parameters should be specified before all else, they do not need to reside in any configuration blocks or appear in any particular order other than appearing before any block parameters. MakefileOutput specifies the output Makefile to generate, example: MakefileOutput = Makefile.out MakefileInputPrepend specifies a text file who's contents will be literally prepended to the MakefileOutput, example: MakefileInputPrepend = makefile_prepend.ini MakefileInputAppend specifies a text file who's contents will be literally appended to the MakefileOutput, example: MakefileInputAppend = makefile_append.ini MessageConfigStartup specifies any arbitary string you want to show just before pconf starts scanning your system, example: MessageConfigStartup = Checking your system... MessagePlatformUnsupported specifies any arbitary string you want to show when the specified platform is not defined in the platforms.ini file, example: MessagePlatformUnsupported = Sorry, that platform is not supported, \ please try a different or generic platform if available. Use --listall \ to obtain a complete list of platforms. MessageDependFailed specifies any arbitary string you want to show when one or more dependencies of the selected platform is not met, example: MessageDependFailed = Your missing some dependencies, use --force \ if you want to keep going next time. MessageSuccess specifies any arbitary string you want to show when pconf is done configuring and generating the MakefileOutput, example: MessageSuccess = Type `make' to compile the program. PARAMETER: PLATFORMS -------------------- Platform specifies the start of a `platform specification block', the value must be the name of the platform (preferably fetched from uname), example: Platform = Linux Platform = UNIX Once this value has been specified, subsequent platform related parameters affect this `platform specification block' untill another Platform is specified or end of file. Description specifies the description of this platform, it may contain some release notes or remarks that may not be readily apparent to the end user, example: Description = UNIX is generic, pick a more specific platform if \ available. PREFIX specifies the prepended directory for installing the program, for distributed UNIXes the value is /usr/local/ and plain UNIXes is /usr/. This value can be overridden from the command line using --prefix. Example: PREFIX = /usr/ CFLAGS specifies the standard compiler flags for the platform, do not include any compiler flags for particular features (see FeatureCFLAGS). Example: CFLAGS = -DNON_STANDARD -DWIERD_STUFF INC_DIRS specifies additional include directories that the platform does not normally search for, do not include any include directories for particular features (see FeaturesINC_DIRS). Example: INC_DIRS = -I/usr/nonstandard/include/ LIBS specifies the standard libraries for the platform that the program needs to link to, do not include any libraries for particular features (see FeatureLIBS). Example: LIBS = -lnonstandard -lm LIB_DIRS specifies the standard library paths for the platform that the libraries specified in the LIBS parameter need to look for, do not include any libraries for particular features (see FeatureLIB_DIRS). Example: LIB_DIRS = -I/usr/nonstandard/lib/ PlatformSearchPathInclude specifies an include path that is known to be on the platform (values must be absolute paths, may be specified multiple times), example: PlatformSearchPathInclude = /usr/include/ PlatformSearchPathInclude = /usr/nonstandard/include/ PlatformSearchPathLib specifies a library path that is known to be on the platform (values must be absolute paths, may be specified multiple times), example: PlatformSearchPathLib = /lib/ PlatformSearchPathLib = /usr/lib/ PlatformSearchPathEtc specifies a configuration files path that is known to be on the platform (values must be absolute paths, may be specified multiple times), example: PlatformSearchPathEtc = /etc/ PlatformSearchPathEtc = /usr/etc/ PlatformSearchPathBin specifies a program files path that is known to be on the platform (values must be absolute paths, may be specified multiple times), example: PlatformSearchPathBin = /bin/ PlatformSearchPathBin = /sbin/ PlatformSearchPathBin = /usr/bin/ PlatformSearchPathBin = /usr/sbin/ PlatformSearchPathBin = /usr/games/ PlatformSearchPathBin = /usr/X11R6/bin/ PlatformSearchPathData specifies a data files path that is known to be on the platform (values must be absolute paths, may be specified multiple times), example: PlatformSearchPathData = /usr/share/icons/ PlatformSearchPathData = /usr/nonstandard/themes/ PARAMETER: FEATURE ------------------ PlatformFeature specifies the start of a `feature specification block', the value must be the name of the feature (any arbitary but user recognizeable name can be used), example: PlatformFeature = X Window Systems PlatformFeature = Imlib PlatformFeature = LibJSW This parameter must be specified after a Platform parameter. Once this value has been specified, subsequent feature related parameters affect this `feature specification block' untill another PlatformFeature is specified or end of file. Features can be enabled or disabled from the command line using --enable- or --disable- where is the name of a PlatformFeature specified value. Description specifies the description of this feature, it should contain a short sentence describing the propose of this feature and when to use it. Example: Description = For joystick support, only available on Linuxes URLHomePage specifies the url (ie used with web browsers and ftp clients) to specify the web page for this particular feature, example: URLHomePage = http://wolfpack.twu.net/libjsw/ URLDownload specifies the url of where to download required compoents for this feature, example: URLDownload = ftp://fox.mit.edu/pub/something.tar.bz2 MustExist specifies the default critera for existance of this feature; if the value is Yes then this feature must be found on the system or else configuration fails, if the value is No then this feature is not searched for on the syste unless the user specificalled --enable'ed this feature from the command line, if the value is Preferred then this feature is searched for on the system and will be enabled if it is found or disabled if it is not found, examples: MustExist = Yes MustExist = Preferred MustExist = No FeatureCFLAGS specifies a list of compiler flags to append to the CFLAGS parameter's value if this feature is found and enabled, example: FeatureCFLAGS = -DHAVE_X FeatureINC_DIRS specifies a list of include directories to append to the INC_DIRS parameter's value if this feature is found and enabled, example: FeatureINC_DIRS = -I/usr/nonstandard/include/ FeatureLIBS specifies a list of libraries to append to the LIBS parameter's value if this feature is found and enabled, example: FeatureLIBS = -lX11 -lXext FeatureLIB_DIR specifies a list of librariy directories to append to the LIB_DIRS parameter's value if this feature is found and enabled, example: FeatureLIB_DIR = -L/usr/X11R6/lib/ PARAMETER: FEATURE DEPENDENCY ----------------------------- FeatureDepend specifies the start of a `dependency specification block', the value must be the name of the dependency (preferably a conical package name), example: FeatureDepend = X11-lib This parameter must be specified after a PlatformFeature parameter. Once this value has been specified, subsequent dependency related parameters affect this `dependency specification block' untill another FeatureDepend is specified or end of file. DependType specifies the type of this dependency, valid values can be; Program, Library, Header, Config, or Data which will indicate the location of the dependency objects to be searched for in the paths (respectivly) PlatformSearchPathBin, PlatformSearchPathLib, PlatformSearchPathInclude, PlatformSearchPathEtc, and PlatformSearchPathData. Example: DependType = Library Which means this dependencie's files will be searched for in the paths defined by PlatformSearchPathLib parameters. MustExist specifies if this dependencie's objects must exist. This value should always be Yes. MustExist = Yes DependPath specifies the name of the object (partial path allowed as needed, but should never be absolute path). This value is searched for depending on this dependency type (specified by DependType) in the appropriate PlatformSearchPath* parameters, example: DependPath = libX11.so DependGrepString specifies the name of a string to search for in a matched dependent object (which means this parameter must be specified after each DependPath parameter!), example: DependPath = libX11.so DependGrepString = XOpenDisplay SAMPLES ------- Example of Linux platform support, this is just one platform section specifying Linux specific details and one feature for X Window Systems (Note that this is not a compelte Linux platform support, you may need to add more paths and related details): MakefileOutput = Makefile.out Platform = Linux Description = Penguins rule! PREFIX = /usr/ CFLAGS = LIBS = -lm LIB_DIR = PlatformSearchPathInclude = /usr/include/ PlatformSearchPathInclude = /usr/X11R6/include/ PlatformSearchPathLib = /lib/ PlatformSearchPathLib = /usr/lib/ PlatformSearchPathLib = /usr/X11R6/lib/ PlatformSearchPathEtc = /etc/ PlatformFeature = X Window Systems MustExist = Preferred FeatureLIBS = -lX11 -lXext FeatureLIB_DIR = -L/usr/X11R6/lib/ FeatureDepend = X11-lib DependType = Library MustExist = Yes DependPath = libX11.so DependGrepString = XOpenDisplay FeatureDepend = X11-devel DependType = Header MustExist = Yes DependPath = X11/Xlib.h DependGrepString = XNextEvent When pconf is runned with the platforms.ini (that contains the above data) and the platform name "linux" the above will be matched and pconf will begin checking for any features and its dependencies. Since feature `X Window Systems' is set to Preferred, pconf will check if it exists and then decide to enable it or not: pconf platforms.ini linux To specifically require that `X Window Systems' be enabled: pconf platforms.ini linux --enable-"X Window Systems" And the same, with an override of the prefix: pconf platforms.ini linux --prefix=/tmp/ --enable-"X Window Systems" List of all platforms in any platforms.ini can be obtained with any of the following (incrementing in detail): pconf platforms.ini pconf platforms.ini --list pconf platforms.ini --listall The portion of the output Makefile (specified by MakefileOutput) generated by pconf will provide values for the parameters; PREFIX, CFLAGS, INC_DIRS, LIBS, LIB_DIRS, CC, and CPP. RFC --- Hopefully you have noticed by now that from the user end side this is pretty close to how AutoConf implments things with the option of specifying a preset platform and platforms configuration file which both can be specified via script. Platform Configurator was created due to the lack of documentation and problems our corperation has encountered with it. We understand that AutoConf has worked for others but with the time and effort that we have expended to adapt and use AutoConf has not been negateful over the option of creating our own pconf system. If you find pconf useful, you are free to use it under the GNU public license. Please send comments and questions to WPE, for list of contact addresses see http://wolfpack.twu.net/contacts.html