Bug 211949 - PMake - A Tutorial Chapter 2.5
Summary: PMake - A Tutorial Chapter 2.5
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: Chris Rees
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2016-08-17 17:29 UTC by Dennis Jensen
Modified: 2018-12-23 21:24 UTC (History)
4 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Dennis Jensen 2016-08-17 17:29:59 UTC
This also effects the following webpage:

https://www.freebsd.org/doc/en/books/pmake/parellelism.html


I read the following paragraph and then printed the entire contents of 2.5 and had several other people read it and we all got the same general impression which I outline after displaying the paragraph in question:

*********************************************************************************

There are several problems you are likely to encounter. One is that some makefiles (and programs) are written in such a way that it is impossible for two targets to be made at once. The program xstr, for example, always modifies the files strings and x.c. There is no way to change it. Thus you cannot run two of them at once without something being trashed. Similarly, if you have commands in the makefile that always send output to the same file, you will not be able to make more than one target at once unless you change the file you use. You can, for instance, add a $$$$ to the end of the file name to tack on the process ID of the shell executing the command (each $$ expands to a single $, thus giving you the shell variable $$). Since only one shell is used for all the commands, you will get the same file name for each command in the script.

*********************************************************************************

I am guessing what is being conveyed (or at least seems to be) is not the intent for when the above is read it sounds like the following occurs:

1) That if you have a multiple commands that create/utilize a filename these can only be run 1 at a time otherwise they will step on each other -- understood

2) However a possible work around is to take on $$$$ to the end of the filename so that each file created gets its own unique Pid (or at least that is what it seems to imply anyway) -- aka here is a work around for the problem in item #1

3) However because PMake only operates under one shell the Pid will be the same for every process and as such all these filenames will still be the same.

Synopsis:  Here is a problem, here is a work-around to the problem, but the work-around to the problem will not work.

If this not what is trying to be conveyed then it needs to be reworded in a manner to clarify what it is trying to say -- on the other hand if this is what it is trying to convey I have to ask -- Why include it at all since it just creates confusion ??
Comment 1 Chris Rees freebsd_committer freebsd_triage 2018-12-23 15:45:55 UTC
To be honest, pretty much everything in this article is out of date anyway!

I'd propose either removing it, or at least including a warning that it's only of historical interest.

What do other docs people think?
Comment 2 Mark Linimon freebsd_committer freebsd_triage 2018-12-23 17:57:55 UTC
(In reply to Chris Rees from comment #1)

Agreed.  It needs to be archived somewhere and then deleted.
Comment 3 Benedict Reuschling freebsd_committer freebsd_triage 2018-12-23 18:04:53 UTC
I agree as well. It can always be found in SVN history, so it's not totally lost if we delete it. Since it's outdated so much, there is no need to keep it around anymore.
Comment 4 Chris Rees freebsd_committer freebsd_triage 2018-12-23 18:58:58 UTC
Thanks for the agreement, I'll take it.

I think I'll remove it but put a link in the commit message to an old release link.
Comment 5 commit-hook freebsd_committer freebsd_triage 2018-12-23 21:23:54 UTC
A commit references this bug:

Author: crees
Date: Sun Dec 23 21:22:52 UTC 2018
New revision: 52714
URL: https://svnweb.freebsd.org/changeset/doc/52714

Log:
  Remove the pmake book from the published docs.

  It doesn't at all match either bmake, or the make that bmake replaced
  (confusingly also sometimes referred to as pmake and fmake).  The style
  of the Makefiles does not bear any semblance to ours, the commands are
  different, and so are the options.

  It's a fascinating document, and it's good that it's not going to completely
  disappear; it'll be visible in the older versions [1] as well as being
  searchable, but it's really not something we should have presented as being
  in any way useful documentation nowadays.

  [1] https://docs.freebsd.org/doc/9.0-RELEASE/usr/share/doc/freebsd/en_US.ISO8859-1/books/pmake/book.html

  PR:		doc/211949
  Reviewed by:	linimon
  Reviewed by:	bcr

Changes:
  head/en_US.ISO8859-1/books/Makefile
  head/en_US.ISO8859-1/books/pmake/