Page MenuHomeFreeBSD

Document cargo.mk in the Porter's Handbook
ClosedPublic

Authored by tobik on May 18 2018, 5:32 AM.
Tags
None
Referenced Files
Unknown Object (File)
Wed, Mar 6, 4:12 AM
Unknown Object (File)
Dec 25 2023, 2:58 AM
Unknown Object (File)
Dec 23 2023, 12:04 AM
Unknown Object (File)
Nov 12 2023, 3:41 AM
Unknown Object (File)
Nov 10 2023, 6:55 AM
Unknown Object (File)
Nov 9 2023, 3:39 AM
Unknown Object (File)
Nov 8 2023, 9:54 PM
Unknown Object (File)
Nov 8 2023, 6:11 PM
Subscribers

Details

Summary

This is very much a work in progress right now. I haven't even run a
spell checker over it and not all knobs are documented.

Diff Detail

Repository
rD FreeBSD doc repository - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

0mp requested changes to this revision.May 18 2018, 12:03 PM

Great job!

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
937 ↗(On Diff #42685)

I'd be more specific. The generated Cargo crates information does not go into the Makefile unless the porter actually redirects the output of make cargo-crates to Makefile.

It's a small thing, however.

977 ↗(On Diff #42685)

This is not all. Now the porter should run make cargo-crates-licenses and probably add a LICENSE block looking more or less like this:

LICENSE= APACHE20 MIT UNLICENSE
LICENSE_COMB= multi
This revision now requires changes to proceed.May 18 2018, 12:03 PM
en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
244–245 ↗(On Diff #42685)

Add an <xref linkend="xxx"> to the real documentation, so that people who get here find it.

  • Add link to the real documentation from the short USES chapter
tobik added inline comments.
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
937 ↗(On Diff #42685)

Ok, I'll reword this slightly.

977 ↗(On Diff #42685)

I plan on adding an example for cargo-crates-licenses.

But I intentionally left out the LICENSE* bits in the current example. It is already document in detail in the licenses chapter, so I feel like this does not belong here.

  • Hopefully make it clearer what to do with make cargo-crates output
  • Add examples for CARGO_FEATURES and cargo-crates-licenses
tobik marked 2 inline comments as done.
  • Document all the knobs in no particular order
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
822 ↗(On Diff #42756)
that use <application>Cargo</application>
999 ↗(On Diff #42756)

missing blank line before and after the <para>.

1005–1007 ↗(On Diff #42756)

blank lines.

1016 ↗(On Diff #42756)
of this command

I don't think it adds anything to repeat it.

1016–1017 ↗(On Diff #42756)

blank lines.

1039–1040 ↗(On Diff #42756)

blank lines.

1041 ↗(On Diff #42756)

clean is of no use here.

1057–1059 ↗(On Diff #42756)

blank lines.

1106 ↗(On Diff #42756)

blank line.

tobik marked 10 inline comments as done.
  • Add missing blank lines
  • Improve wording in some places
  • Move make clean to a separate step

There are a few other whitespace inconsistencies, I think installing textproc/igor and running it on the file igor -R en_US.ISO8859-1/books/porters-handbook/special/chapter.xml (and maybe also run igor -yR en_US.ISO8859-1/books/porters-handbook/special/chapter.xml to get style corrections.)

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
832–833 ↗(On Diff #42796)

Might be a good idea to add a third column in the middle "default" to put all the default values in it instead of having them mixed with the description of the variables.

870 ↗(On Diff #42796)
<varname>MAKE_ENV</varname>
891 ↗(On Diff #42796)
<package role="port">lang/rust</package>
915 ↗(On Diff #42796)
Use the default <buildtarget>do-install</buildtarget>.
984 ↗(On Diff #42796)

s/distfile/distribution file/

985 ↗(On Diff #42796)

Remove extra newline before </para>.

1078 ↗(On Diff #42796)

Remove extra blank line.

tobik marked 7 inline comments as done.
  • Add default column for all variables
  • Fix markup as noted by @mat
  • s/distfile/distribution file/
  • Pet igor
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
834 ↗(On Diff #42920)

I don't fancy "Means" here, each time I read it, I stop and wonder what resources/wealth have to do about it. I think most table listing variables have "Description" here, I think it would be a bit more clear.

other than that, I don't see anything inherently wrong about it, it builds, so if it is complete, do ship it :-)

This revision is now accepted and ready to land.May 25 2018, 2:10 PM
This revision was automatically updated to reflect the committed changes.
tobik marked 2 inline comments as done.