Page MenuHomeFreeBSD
Differential D11523 Diff 30737 en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

Changeset View

Standalone View

View Options

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

Show First 20 Lines • Show All 43 Lines • ▼ Show 20 Lines
PKGNAMEPREFIX= ja- PKGNAMEPREFIX= ja-
DISTNAME= xdvi-pl18 DISTNAME= xdvi-pl18
[set this if the source is not in the standard ".tar.gz" form] [set this if the source is not in the standard ".tar.gz" form]
EXTRACT_SUFX= .tar.Z EXTRACT_SUFX= .tar.Z
[section for distributed patches -- can be empty] [section for distributed patches -- can be empty]
PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
[If the distributed patches were not made relative to ${WRKSRC},
wblockUnsubmitted
Not Done
Inline Actions

Let's make these real DocBook callouts so they are not mixed with the actual Makefile contents.
See https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/docbook-markup-block-elements.html#docbook-markup-callouts

wblock: Let's make these real DocBook callouts so they are not mixed with the actual Makefile contents.
ultimaAuthorUnsubmitted
Not Done
Inline Actions

Not sure I completely understand how the callouts work, can you check if this looks correct? If so, should this be done for the rest of the sample Makefile?

ultima: Not sure I completely understand how the callouts work, can you check if this looks correct? If…
matUnsubmitted
Not Done
Inline Actions

Well, if all the [...] go into callouts, the page will be unreadable, there will be 20+ callouts, and people will keep scrolling up and down to figure out what means what.

mat: Well, if all the [...] go into callouts, the page will be unreadable, there will be 20+…
matUnsubmitted
Not Done
Inline Actions

The ref is co-patch-dist-strip.

mat: The ref is `co-patch-dist-strip`.
this may need to be tweaked]
PATCH_DIST_STRIP= -p1
[maintainer; *mandatory*! This is the person who is volunteering to [maintainer; *mandatory*! This is the person who is volunteering to
handle port updates, build breakages, and to whom a users can direct handle port updates, build breakages, and to whom a users can direct
questions and bug reports. To keep the quality of the Ports Collection questions and bug reports. To keep the quality of the Ports Collection
as high as possible, we no longer accept new ports that are assigned to as high as possible, we do not accept new ports that are assigned to
matUnsubmitted
Done
Inline Actions

while you are changing this file, s/we no longer accept/we do not accept/

mat: while you are changing this file, `s/we no longer accept/we do not accept/`
"ports@FreeBSD.org".] "ports@FreeBSD.org".]
MAINTAINER= asami@FreeBSD.org MAINTAINER= asami@FreeBSD.org
COMMENT= DVI Previewer for the X Window System COMMENT= DVI Previewer for the X Window System
[license -- should not be empty] [license -- should not be empty]
LICENSE= BSD2CLAUSE LICENSE= BSD2CLAUSE
LICENSE_FILE= ${WRKSRC}/LICENSE LICENSE_FILE= ${WRKSRC}/LICENSE
[dependencies -- can be empty] [dependencies -- can be empty]
RUN_DEPENDS= gs:print/ghostscript RUN_DEPENDS= gs:print/ghostscript
[this section is for other standard bsd.port.mk variables that do not [If it requires GNU make, not /usr/bin/make, to build...]
USES= gmake
[If it is an X application and requires "xmkmf -a" to be run...]
matthewUnsubmitted
Done
Inline Actions

This has a different effect than the original code, since in:

USES= gmake
USES= imake

the 2nd line cancels out the first... However, I think your version is more like
what was intended.

matthew: This has a different effect than the original code, since in: ``` USES= gmake USES= imake ```…
matUnsubmitted
Done
Inline Actions

No, this, here, is not supposed to be a working Makefile, it is supposed to show what you might want. Using both at the same time, here, is a bad idea. It kinda tells you that you are going to need both, whereas there are only 6 ports using both, out of the 270+ using imake and 4k using gmake.

So I would rather this be kept as it was, two separate bits.

mat: No, this, here, is not supposed to be a working Makefile, it is supposed to show what you might…
wblockUnsubmitted
Not Done
Inline Actions

Maybe this is not a good example any more. If multiple options are to be shown, better to show a couple of complete, working sample Makefiles rather than one that does not work as shown.

wblock: Maybe this is not a good example any more. If multiple options are to be shown, better to show…
matUnsubmitted
Not Done
Inline Actions

It never was a good example, it tells you what kind of stuff you can put in the Makefile, and where, but it never was a working example of what to do exactly.
I am not sure it makes sense to have multiple examples either, they would probably get outdated fast.

mat: It never was a good example, it tells you what kind of stuff you can put in the Makefile, and…
ultimaAuthorUnsubmitted
Not Done
Inline Actions

If this samples [ ]comments are all converted to callouts, combining the USES and adding a call out next to them will make it easily understood that they they are for a specific purpose. I think the callout suggestion is a good idea, I am worried though that in the end there will be so many callouts that this sample won't look so great.

ultima: If this samples [ ]comments are all converted to callouts, combining the USES and adding a call…
USES= imake
USE_GITHUB= yes
matUnsubmitted
Done
Inline Actions

should probably add a comment above this to separate it from imake.

mat: should probably add a comment above this to separate it from imake.
GH_ACCOUNT= example
[this section is for other standard bsd.port.mk variables that do not]
belong to any of the above] belong to any of the above]
[If it asks questions during configure, build, install...] [If it asks questions during configure, build, install...]
IS_INTERACTIVE= yes IS_INTERACTIVE= yes
ultimaAuthorUnsubmitted
Done
Inline Actions

Ah, sorry whitespace change isn't relevant

ultima: Ah, sorry whitespace change isn't relevant
[If it extracts to a directory other than ${DISTNAME}...] [If it extracts to a directory other than ${DISTNAME}...]
WRKSRC= ${WRKDIR}/xdvi-new WRKSRC= ${WRKDIR}/xdvi-new
[If the distributed patches were not made relative to ${WRKSRC},
this may need to be tweaked]
PATCH_DIST_STRIP= -p1
[If it requires a "configure" script generated by GNU autoconf to be run] [If it requires a "configure" script generated by GNU autoconf to be run]
GNU_CONFIGURE= yes GNU_CONFIGURE= yes
[If it requires GNU make, not /usr/bin/make, to build...]
USES= gmake
[If it is an X application and requires "xmkmf -a" to be run...]
USES= imake
[et cetera.] [et cetera.]
[If it requires options, this section is for options]
OPTIONS_DEFINE= DOCS EXAMPLES FOO
OPTIONS_DEFAULT= FOO
matUnsubmitted
Done
Inline Actions

maybe add an OPTIONS_SUB=yes here.

mat: maybe add an OPTIONS_SUB=yes here.
[If options will add files to plist]
OPTIONS_SUB=yes
FOO_DESC= Enable foo support
FOO_CONFIGURE_ENABLE= foo
[non-standard variables to be used in the rules below] [non-standard variables to be used in the rules below]
MY_FAVORITE_RESPONSE= "yeah, right" MY_FAVORITE_RESPONSE= "yeah, right"
[then the special rules, in the order they are called] [then the special rules, in the order they are called]
matUnsubmitted
Done
Inline Actions

s/add/change/ or something less terse.

mat: s/add/change/ or something less terse.
pre-fetch: pre-fetch:
i go fetch something, yeah i go fetch something, yeah
post-patch: post-patch:
i need to do something after patch, great i need to do something after patch, great
pre-install: pre-install:
and then some more stuff before installing, wow and then some more stuff before installing, wow
[and then the epilogue] [and then the epilogue]
.include &lt;bsd.port.mk&gt;</programlisting> .include &lt;bsd.port.mk&gt;</programlisting>
<sect1 xml:id="porting-samplem-order"> <sect1 xml:id="porting-samplem-order">
<title>Order of Variables in Port Makefiles</title> <title>Order of Variables in Port Makefiles</title>
<para>The first sections of the <filename>Makefile</filename> <para>The first sections of the <filename>Makefile</filename>
matUnsubmitted
Not Done
Inline Actions

Either <literal>${WRKSRC}</literal> or <filename>${WRKSRC}</filename>

Also, at the end, it should be </para>

mat: Either <literal>${WRKSRC}</literal> or <filename>${WRKSRC}</filename> Also, at the end, it…
must always come in the same order. This standard makes it so must always come in the same order. This standard makes it so
everyone can easily read any port without having to search for everyone can easily read any port without having to search for
variables in a random order.</para> variables in a random order.</para>
ultimaAuthorUnsubmitted
Not Done
Inline Actions

I think the callout list is supposed to be under the programlisting, but I'm not sure what this block should be, or is this correct?

ultima: I think the callout list is supposed to be under the programlisting, but I'm not sure what this…
matUnsubmitted
Not Done
Inline Actions

It won't build with the calloutlist inside the programlisting.

mat: It won't build with the calloutlist inside the programlisting.
<para>The first line of a <filename>Makefile</filename> is always <para>The first line of a <filename>Makefile</filename> is always
a comment containing the <application>Subversion</application> a comment containing the <application>Subversion</application>
version control ID, followed by an empty line. In new ports, it version control ID, followed by an empty line. In new ports, it
looks like this:</para> looks like this:</para>
<programlisting># &dollar;FreeBSD&dollar; <programlisting># &dollar;FreeBSD&dollar;
&nbsp;</programlisting> &nbsp;</programlisting>
▲ Show 20 Lines • Show All 352 Lines • ▼ Show 20 Lines <varname>USE_<replaceable>x</replaceable></varname>.</para>
<para>Keep related variables close together. For example, if <para>Keep related variables close together. For example, if
using <link using <link
linkend="makefile-master_sites-github"><varname>USE_GITHUB</varname></link>, linkend="makefile-master_sites-github"><varname>USE_GITHUB</varname></link>,
always put the always put the
<varname>GH_<replaceable>*</replaceable></varname> variables <varname>GH_<replaceable>*</replaceable></varname> variables
right after it.</para> right after it.</para>
</sect2> </sect2>
<sect2 xml:id="porting-samplem-options"> <sect2 xml:id="porting-samplem-options">
matUnsubmitted
Done
Inline Actions

dupplicated id.

mat: dupplicated id.
<title>Options</title> <title>Options</title>
<para>If the port uses the <link <para>If the port uses the <link
wblockUnsubmitted
Done
Inline Actions

s/are definable/can be defined/

wblock: s/are definable/can be defined/
linkend="makefile-options">options framework</link>, define linkend="makefile-options">options framework</link>, define
wblockUnsubmitted
Done
Inline Actions

Remove "the", and "belong to" is kind of confusing. "belong in" is a little better, but how is the reader supposed to know where things belong?

wblock: Remove "the", and "belong to" is kind of confusing. "belong in" is a little better, but how is…
<varname>OPTIONS_DEFINE</varname> and <varname>OPTIONS_DEFINE</varname> and
matUnsubmitted
Done
Inline Actions

You should probably add some examples here, this is too vague.

mat: You should probably add some examples here, this is too vague.
ultimaAuthorUnsubmitted
Not Done
Inline Actions

I think this section is looking much better now!

ultima: I think this section is looking much better now!
<varname>OPTIONS_DEFAULT</varname> first, then the other <varname>OPTIONS_DEFAULT</varname> first, then the other
<varname>OPTIONS_<replaceable>*</replaceable></varname> <varname>OPTIONS_<replaceable>*</replaceable></varname>
variables first, then the variables first, then the
<varname><replaceable>*</replaceable>_DESC</varname> <varname><replaceable>*</replaceable>_DESC</varname>
descriptions, then the options helpers. Try and sort all of descriptions, then the options helpers. Try and sort all of
matUnsubmitted
Not Done
Inline Actions

Move the replaceable bits inside varname.

mat: Move the replaceable bits inside varname.
those alphabetically.</para> those alphabetically.</para>
matUnsubmitted
Not Done
Inline Actions

Please remove the evil PORTDATA, we want to remove it.

mat: Please remove the evil PORTDATA, we want to remove it.
</sect2> </sect2>
<sect2 xml:id="porting-samplem-rest"> <sect2 xml:id="porting-samplem-rest">
<title>The Rest of the Variables</title> <title>The Rest of the Variables</title>
<para>And then, the rest of the variables that are not <para>And then, the rest of the variables that are not
mentioned in the previous blocks.</para> mentioned in the previous blocks.</para>
</sect2> </sect2>
▲ Show 20 Lines • Show All 42 Lines • Show Last 20 Lines