os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Remove LOOP_VAR and LOOP_OPTIONS description and replace it with MASTERDIR.

Browse source 
Add note about ${X11BASE}/lib/X11/fonts/local.  Add info about bsd.port.pre.mk.
This commit is contained in:
Satoshi Asami 1998-11-23 06:28:07 +00:00
parent 8a6c2c722f
commit 1b258442c1
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=3824
1 changed files with 125 additions and 49 deletions

174
handbook/porting.sgml
View file

@ -1,4 +1,4 @@
<!-- $Id: porting.sgml,v 1.114 1998-11-07 11:50:45 asami Exp $ -->
<!-- $Id: porting.sgml,v 1.115 1998-11-23 06:28:07 asami Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>Making a port yourself<label id="porting"></heading>
@ -1042,60 +1042,57 @@ ${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....
default format of the system.
<sect2>
<heading>Ports that build multiple versions of packages<label id="porting:package-loop"></heading>
<heading><tt/MASTERDIR/<label id="porting:masterdir"></heading>
<p>If your port can build different versions of packages by
having the user set a variable, use <tt/LOOP_VAR/ and
<tt/LOOP_OPTIONS/. The former is the name of the variable
and the latter is the list of values you want it to take.
You should also put <tt>&dollar;{LOOP_VAR}</tt> as part of
<tt><ref id="porting:pkgname" name="PKGNAME"></tt> so the
packages will indeed have different names.
<p>If your port needs to build slightly different versions
of packages by having a variable (for instance, resolution
or paper size) take different values, create one
subdirectory per package to make it easier for users to
see what to do, but try to share as many files as possible
between ports. Typically you only need a very short
Makefile in all but one of the directories if you use
variables cleverly. In the sole Makefiles, you can use
<tt>&dollar;{MASTERDIR}</tt> to specify the directory
where the rest of the files are. Also, use a variable as
part of <tt><ref id="porting:pkgname" name="PKGNAME"></tt>
so the packages will have different names.
<p>It is also recommended that you specify a default and
print out a message about available choices if the user
doesn't specify a value for the variable. Here is an
example:
<p>This will be best demostrated by an example. This is
part of <tt>japanese/xdvi300/Makefile</tt>:
<tscreen><verb>
:
PKGNAME= ja-xdvi${RESOLUTION}-17
:
LOOP_VAR= RESOLUTION
LOOP_OPTIONS= 118 240 300 400
:
.if !defined(RESOLUTION)
RESOLUTION= 300
RESOLUTION_UNSPECIFIED= yes
.else
# default
RESOLUTION?= 300
.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \
${RESOLUTION} != 300 && ${RESOLUTION} != 400
RESOLUTION_INVALID= yes
.endif
.endif
pre-fetch:
.if defined(RESOLUTION_UNSPECIFIED)
@echo "Building xdvi with ${RESOLUTION}dpi fonts."
@echo "Set the environment variable RESOLUTION if you want"
@echo "it to use other resolutions."
@echo "Possible values are: 118, 240, 300 (default) and 400."
.elif defined(RESOLUTION_INVALID)
@echo "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
@echo "Possible values are: 118, 240, 300 (default) and 400."
@/usr/bin/false
@${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
@${ECHO} "Possible values are: 118, 240, 300 (default) and 400."
@${FALSE}
.endif
</verb></tscreen>
<tt/bsd.port.mk/ will define a special target
<tt/package-loop/ which will cause a "<tt>make clean
package</tt>" loop to go around four times, with the value
of <tt/RESOLUTION/ set to 118, 240, 300 and 400, to build
four separate packages.
<tt>japanese/xdvi300</tt> also has all the regular
patches, package files, etc. If you type `<tt/make/'
there, it will take the default value for the resolution
(300) and build the port normally.
<p>It will also cause the <tt/describe/ target to print out
four lines, one for each value of
<tt>&dollar;{RESOLUTION}</tt>. This way all the package
names will go into the <tt/INDEX/ file and show up in the
installation menu.
<p>As for other resolutions, this is the <em/entire/
<tt>xdvi118/Makefile</tt> (minus the comments):
<tscreen><verb>
RESOLUTION= 118
MASTERDIR= ${.CURDIR}/../xdvi300
.include "${MASTERDIR}/Makefile"
</verb></tscreen>
(<tt>xdvi240/Makefile</tt> and <tt>xdvi400/Makefile</tt>
are similar). The <tt>&dollar;{MASTERDIR}</tt> definition
tells <tt/bsd.port.mk/ that the regular set of
subdirectories like <tt>&dollar;{PATCHDIR}</tt> and
<tt>&dollar;{PKGDIR}</tt> are to be found under
<tt/xdvi300/. The <tt/RESOLUTION=118/ line will override
the <tt/RESOLUTION?=300/ line in <tt>xdvi300/Makefile</tt>
and the port will be built with resolution set to 118.
<sect2>
<heading>Shared library versions</heading>
@ -1235,6 +1232,17 @@ ${PREFIX}/man/ja/man4/baz.4.gz
`<tt>/usr/X11R6/lib/libXm.a</tt>', so there is no need to
add `<tt>-L</tt>' or `<tt>-l</tt>' in front.
<sect2>
<heading>X11 fonts</heading>
<p>If your port installs fonts for the X window system, put
them in <tt>&dollar;{X11BASE}/lib/X11/fonts/local</tt>. This
directory is new to XFree86 release 3.3.3. If it does not
exist, please create it, and print out a message urging the
user to update their XFree86 to 3.3.3 or newer, or at least
add this directory to the font path in
<tt>/etc/XF86Config</tt>.
<sect2>
<heading>Info files</heading>
<p>The new version of texinfo (included in 2.2.2-RELEASE and
@ -1707,7 +1715,8 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}
use them.
<sect2>
<heading>Differentiating operating systems and OS versions</heading>
<heading>Differentiating operating systems and OS versions<label
id="porting:versions"></heading>
<p>You may come across code that needs modifications or
conditional compilation based upon what version of UNIX it is
@ -1855,6 +1864,74 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}
screwed up and used it in the wrong place does not mean
you should do so too.
<sect2>
<heading>Writing something after <tt/bsd.port.mk/</heading>
<p>Do not write anything after the `<tt>.include
&lt;bsd.port.mk&gt;</tt>' line. It usually can be avoided
by including <tt/bsd.port.pre.mk/ somewhere in the middle of
your Makefile and <tt/bsd.port.post.mk/ at the end. The
former only defines a few variables, which can be used in
tests in Makefiles; the latter defines the rest. Here are
some important variables defined in <tt/bsd.port.pre.mk/.
(This is not the entire list; please read <tt/bsd.port.mk/
for the complete list.)
<descrip>
<tag>&dollar{ARCH}</tag> The archetecture, as returned by
`<tt>uname -m</tt>' (e.g., `i386').
<tag>&dollar{OPSYS}</tag> The operating system type, as returned by
`<tt>uname -s</tt>' (e.g., `FreeBSD').
<tag>&dollar{OSREL}</tag> The release version of the operating
system (e.g., `2.1.5', `2.2.7').
<tag>&dollar{OSVERSION}</tag> The numeric version of the
operating system, same as <ref id="porting:versions"
name="__FreeBSD_version"> above.
<tag>&dollar{PORTOBJFORMAT}</tag> The object format of the
system (`aout' or `elf').
<tag>&dollar{LOCALBASE}</tag> The base of the `local' tree
(e.g., `/usr/local/').
<tag>&dollar{X11BASE}</tag> The base of the `X11' tree
(e.g., `/usr/X11R6/').
<tag>&dollar{PREFIX}</tag> Where the port installs itself (see
<ref id="porting:prefix" name="more on PREFIX">).
</descrip>
<p>Note: if you have to define the variables <tt/USE_IMAKE/,
<tt/USE_X_PREFIX/ or <tt/MASTERDIR/, do so before including
<tt/bsd.port.pre.mk/; everything else can be either before
or after <tt/bsd.port.pre.mk/. Here are some examples of
things you can write after <tt/bsd.port.pre.mk/:
<tscreen><verb>
# no need to compile lang/perl5 if perl5 is already in system
.if ${OSVERSION} > 300003
BROKEN= perl is in system
.endif
# only one shlib version number for ELF
.if ${PORTOBJFORMAT} == "elf"
TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}
.else
TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
.endif
# software already makes link for ELF, but not for a.out
post-install:
.if ${PORTOBJFORMAT} == "aout"
${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
.endif
</verb></tscreen>
<sect2>
<heading>Install additional documentation</heading>
@ -1945,7 +2022,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}
split it up into one source file per patch file.
<sect2>
<heading>PREFIX</heading>
<heading>PREFIX<label id="porting:prefix"></heading>
<p>Do try to make your port install relative to
<tt>&dollar;{PREFIX}</tt>. (The value of this variable will be
@ -2281,9 +2358,8 @@ msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh
well (like `kinput2').
<item>If the port can be built with different <ref
id="porting:package-loop" name="hardcoded defaults">
(usually specified as environment variables or on the
<tt>make</tt> command line), the
id="porting:masterdir" name="hardcoded defaults">
(usually part of the directory name in a family of ports), the
`<tt>&lt;compiled.specifics&gt;</tt>' part should state the
compiled-in defaults (the hyphen is optional). Examples are
papersize and font units.