Three New Chapter for Porters Handbook

[russ.haley_gmail.com]

Summary

This is three new chapters for the porters handbook with the following intent:

• Introduce the ports system
• Describe the tools used for creating a port
• Describe the bsd ports make process
• Describe the files and folders in a port
• Explain the process of creating a port patch (or new port) with the existing tools
• Explain the process for submitting a patch and what to expect.

These chapters are created from three sources: the original content, a donation by koobs@, and my own contributions. This is a very rough draft and is incomplete. The files do not currently build. For more background please see the discussion on doc@ titled "Porters Handbook section 4.4"

2017-11-05: RH - Clarification: The intent of this update is to remove the chapters porting-why, quick-porting and slow-porting as all the information has been subsumed into these chapters.

Test Plan

• Get files to build
• Elicit feedback (concurrently with step 1)
• Re-write and re-submit a second draft

[mat]

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

18

s/FreeBSD/&os;/

s/the make(?) build tool/&man.make.1;/

Never use "you" or "your"

the ports tree under <filename>Mk/</filename>.

58

​ compressped tarball) in

59

You could add that it checks the file integrity through a checksum.

61

Don't say that, because THIS MUST NOT BE CHANGED from its default.

75

The optional configure target is run.

78–82

I would really like you not to document this there are only a handful of very old crufty ports doing this, and they should be converted to work with a modern way of doing things.

101

This installs the final set of built files into a staging

108–122

Both of those step are not run when a user types make.

127

same here, don't talk about the scripts. (this goes for the whole document.)

156

We should never talk about modifying bsd.port.mk or even tell people to go and read it.

All the documentation people need should be here, if they need to go read b.p.m we failed.

170–172

So don't talk about it :-)

189–193

there is no such thing a "checksum". Don't document the files directory, it is optional.

211–213

There is already a section about this in the "quick porting" chapter, it should probably be enhanced rather than duplicate things here.

350

It is called distinfo.

357

<title>The <filename>files</filename> directory</title>

[mat]

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

61

Also, it is no longer true with flavors.

[russ.haley_gmail.com]

Thanks so much for the review @mat!

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

18

The &os; ports system utilizes the &man.make.1; build tool to create usable instances of software. Ports contains pre-created "build targets" for most processes required to build software and is extensible to meet any unforseen need. Build targets are instructions that tell &man.make.1; how to perform tasks such as downloading sources, building the software and installation. Build targets for the ports system live under the ports tree under <filename>Mk/</filename>.

58

(typically a compressed archive)

61

<step>

<para>The <buildtarget>extract</buildtarget> target is run.

	  The system looks for the port's distribution file (typically a
	  compressed archive) in
	  <varname>DISTDIR</varname> and unpacks it into a temporary
	  subdirectory specified by <varname>WRKDIR</varname>
	  (resolves to <filename>work</filename> under the top port directory).
	  File integrity is verified by checksuming the download and comparing
	  to the checksum value specifified in the <filename>distinfo</filename> file.
	  </para>
      </step>

75

removed as per next comment

108–122

"a package" is opaque. Can someone give me details on what it is? Is it compatible with pkg(8)? Can it be distributed?

Also, does make install use "the package" or the files from the staging?

156

I've removed all references to the scripts. However, as a developer I humbly disagree about the need to read source code. At a certain point the vernacular only obfuscates what high level languages have been designed to express. I have re-written the final paragraph to remove comments about the sources, but would like to leave the preceding comment directed "at the curious".

189–193

Oops on the checksum. I don't understand why the files directorys' optional status makes it un-worthy of documentation, especially given your prior statement about this containing all information required for ports? Is the directory not required for all patch files?

211–213

Sorry, I wasn't clear enough in my description. My intent is to remove porting-why, quick-porting, and slow porting. All the information in those chapters has been subsumed in the new chapters.

[mat]

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

211–213

Mmmm, I do not think this is a great idea, if the point is just to move things around, then move them around in the existing chapters.

[russ.haley_gmail.com]

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

211–213

In the end I am indifferent to the chapter names. However (and again, with all due respect and appreciation), I think you can agree I have done much more than just moved things around. Also, I fully expect to flesh out or otherwise bring the original content in line with feedback, which has already had substantial changes (to said original text).

Given the above, I think it would be fair to say that the original chapter names are no longer applicable and - in my opinion - were of dubious value at best. Can you provide some reasoning as to why you wish to see the original chapter names preserved?

[mat]

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

211–213

Well, the main problem I see is that unless you copy everything and then modify (which is about the same as changing in place), bits and pieces of documentation will be lost, which I find unacceptable.

[russ.haley_gmail.com]

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

211–213

Of course, quite right. I shall create a new checkout to get it to build first, and then impose the new content on the old chapters for comparison purposes. I will note a request to rename in the future?

[russ.haley_gmail.com]

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

156

Hi mat, the following link to the documentation primer is perhaps a precedent for referring to source code in documentation? I knew I had seen it before, but was unsure where to find it.

https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/make-includes.html

Thoughts?

[julian]

is there a formatted version of this available somewhere so it can be read in final form?

[russ.haley_gmail.com]

In D12921#287341, @julian wrote:

is there a formatted version of this available somewhere so it can be read in final form?

Not yet. People on the mailing list pointed out my embarrassing build mistake so I backtracked to read the documentation primer again. Fingers crossed for this weekend.

[russ.haley_gmail.com]

Well to my surprise it "compiled". Chapter three is all mashed up and this version doesn't have the changes requested by mat. I'll have to get that revision off a different computer.

Be forewarned, this was free form written in one day in a text editor so don't expect too much. I think I've already re-written the last section of chapter 5 as well.

https://drive.google.com/open?id=1tLx8CpL7FxoW0MGQCJrc-Jzqlrt33kvd

[julian]

I tried to read the introduction with a web browser (it's a .html) but it stuck it all together..
can you add some basic formatting?

[russ.haley_gmail.com]

• Updated formatting to make it more readable. Still requires a great deal of work.
• Some revision of the text, no change to the technical content.

[russ.haley_gmail.com]

en_US.ISO8859-1/books/porters-handbook/ph-build-process/chapter.xml

211–213

Hi Mat, I just wanted to say I haven't forgotten about this comment. I've aproached it a few times but with no satisfactory answers. The content is really a complete re-write. I can put together a listing of the source of the content, but there is no real way to diff the chapters.

I'm happy to put that together if you wish, but a far more productive aproach (in my opinion) would be proper community vetting. Thoughts?

[russ.haley_gmail.com]

I've posted the output here: http://envirobotics.ca/portershb/ph-introduction.html

[russ.haley_gmail.com]

Minor update to make section 3.2.2 a little more readable. I'll push the changes here as well http://envirobotics.ca/portershb/tools-introduction.html