illumos / dev-guide Goto Github PK

In the section "Basic illumos workflow", subsection "Victory", the link for "Debugging" goes to integrating.html when it should go to debugging.html:

specifically, in the file called workflow this line looks wrong:
- [Debugging](./integrating.html)

Automatically pull master and rebuild the guide.

@jclulow Any reason not to do this?

(@rzezeski asked if we could pull in some updates and you were traveling: #18 (comment))

I'm happy to do this work, unless there's a reason not to. Ryan would also be happy to spend the cycles on it.

• Deploy key
• Script
• Chef + cron job

I would like to add a glossary section; dev guide itself suggests I should check in before writing this myself. I would propose to make this an appendix, and place it before the documentation license section.

Please let me know thumbs up / thumbs down / thumbs sideways.

Some links are broken, for example it should be:
DTrace guide

but it's:

[http://dtrace.org/guide](DTrace guide)

Under the heading `Component Anatomy, Creating and Modifying Components':

"It first covers the anatomy of different libraries, commands, and kernel modules, and device drivers."

There is an extra `and', after commands. Maybe a leftover.

When users navigate to https://illumos.org/books/dev, the web server is implicitly appending /index.html. This page doesn't currently exist by default. We've been creating (as a deployment step) a symlink from index.html to intro.html to work around this, but it'd be best to just do so directly in the Makefile.

There are a few scattered typos and awkward wordings in the introduction to the guide, including under the section "What is illumos," "Guide layout", and Conventions.

The "Appendix: Glossary of Terms" page not updated to the fact that we already eliminated
the Sun Studio lint dependency too ("Sun Studio" term).

We use the smatch static code analysis tool.

The phasing-out of lint started with this message from the illumos-developer mailing list:
[HEADS-UP] GCC 7 shadow compiler; no more lint.

There is an IPD (illumos Project Discussion) for this too: IPD 2 Running smatch for Illumos builds.

Smatch introduced in Jan 5 2019 with this commit 10063 basic support for smatch,
and from Jul 18 2019 this is the default tool, see this commit: 11462 enable smatch by default.

The "Lint; linting" term have to be updated too, to indicate that even if we don't use
the Sun Studio lint tool anymore, someone might use the "linting" term
interchangeably with "doing automated static code analysis" -- now with smatch.

Throughout the guide, the guide is called "Illumos developer's guide" however the page titles call it "illumos ON Developer's Guide". This is inconsistent at the very least, and mildly confusing at worst - illumos is what used to be ON. There's no Illumos ON.

The path referred in the creation of illumos.sh, i.e. /opt/onbld/env/illumos does not exist in SmartOS.

I really don’t know where to get this file.

illumos Guidelines and Principles is referenced in the guide, but this section does not exist

In this file:
For the full set of illumos lists, as well as, various distribution-specific lists, please see [The illumos wiki Mailing list page](http://wiki.illumos.org/display/illumos/illumos+Mailing+Lists).
should be:
For the full set of illumos lists, as well as, various distribution-specific lists, please see [The illumos Mailing lists page](https://illumos.org/docs/community/lists/).

This is a low priority issue because the visitor will be automatically redirected to the new mailing lists page.

illumos-docs had a bunch of overhauls here that got missed including streamlining code review, etc. We should update the content here.

Very minor typos and word choice in help section.

Broken link to illumos mailing lists also in this section.

in the layout file at line 84, pacakge -> package

We just got reported that https://illumos.org/books/dev/help.html still refers to irc.freenode.net it should refer to libera of course :)

Remember the power of SOURCEDEBUG=yes.

In the section Setting the path to our workspace, there is a grammatical error in the first paragraph:

#### Setting the path to our workspace
Next, we need to make sure that `nightly` and other tools can find where our
The variables that we want to modify are `GATE` and `CODEMGR_WS`. We're going to
set `GATE` to the name of the directory that we're in and `CODEMGR_WS` to the
[...snip...]

It looks like the first line of the paragraph should have been deleted (or completed).

#### Setting the path to our workspace
Next, we need to make sure that `nightly` and other tools can find where our Illumos
directory is. This requires modifying 2 variables: `GATE` and `CODEMGR_WS`. We're going to
set `GATE` to the name of the directory that we're in and `CODEMGR_WS` to the
[...snip...]

Current doc doesn't mention that ONNV_BUILDNUM may need incrementing in most or all install target environments.

Error in obtaining closed binaries section ("operating" instead of "operating system"):

 ### Obtaining Closed Binaries
While Sun made almost all of the operating open source, there are still a few
closed components that the illumos community is replacing. You can obtain a copy

Should be:

 ### Obtaining Closed Binaries
While Sun made almost all of the operating system open source, there are still a few
closed components that the illumos community is replacing. You can obtain a copy

http://illumos.org/books/dev/workflow.html#setting-up-illumossh talks about $GATE which has been removed recently.

2nd paragraph, unnecessary 'for':

 If a build fails, the first stop for is usually the `nightly.log`. Every run of
[...snip...]

In the developer guide under section Setting the path to our workspace we explain setting
the CODEMGR_WS variable as: export CODEMGR_WS="/ws/rm/$GATE"

This could be made more dynamic by setting variable like:

export CODEMGR_WS="git rev-parse --show-toplevel"

@rmustacc Does this make sense? If so, I'll send a patch updating this.

http://illumos.org/man/1/nightly

With the manual page restructuring coming in, we should update the set of manual pages here.

line 16, PTYHON.

One of the examples ( https://github.com/illumos/dev-guide/blob/master/workflow#L378 ) is incorrectly formatted on http://illumos.org/books/dev/workflow.html - the code is concatenated in one line.

In the Testing section of the Basic illumos Workflow section, when it mentions using onu to create the new build environment the example command is missing the -d flag to point it to the locally built packages. Currently it is:

# onu -t new-nightly-be
#

When it should be:

# onu -t new-nightly-be -d /path/to/gate/packages/<arch>/nightly/
#

Missing the -d flag results in it trying to reach the ipkg.sfbay domain which no longer exists and it fails because it cannot resolve the hostname.