9:31 a.m.
A simple patch to update the morph manual page with a basic description
of what it does within the context of Baserock, and a pointer to the
Baserock wiki for more information.
* Repository: git://roadtrain.codethink.co.uk/baserock/morph
* Branch: joeldillon/documentation
* Commit: cf70941e16afe6f6b8509e25446bea441ac99353
Joel Dillon (1):
Modified man page to go into more detail about what morph does
morph.1.in | 34 +++++++++++++++++++++++++++++-----
1 file changed, 29 insertions(+), 5 deletions(-)
--
1.7.9.5
9:31 a.m.
New subject: [PATCH] Modified man page to go into more detail about what morph does
---
morph.1.in | 34 +++++++++++++++++++++++++++++-----
1 file changed, 29 insertions(+), 5 deletions(-)
diff --git a/morph.1.in b/morph.1.in
index 38bff72..639f457 100644
--- a/morph.1.in
+++ b/morph.1.in
@@ -23,7 +23,34 @@ Baserock is an embedded Linux system.
is its workflow tool.
It manages building binaries,
and branching and merging of the entire system.
-See the Baserock home page for more information.
+Morph is designed to turn collections of git repositories into system images
+using morphology files to define their dependencies.
+.PP
+A
+.B system
+image is defined as a group of
+.B strata
+describing subsystems,
+each of which comprises a series of
+.B chunks
+, each of which in turn corresponds
+to an individual upstream project. For example, there might be a 'generic
+developer system' system morphology, containing a stratum for the basic
+bootable system and another for developer tools; the latter would then have
+individual chunks for make, gcc, binutils and so forth.
+.PP
+A chunk is a git repository based on an individual upstream project's revision
+control system (converted into git if upstream does not already use it), which
+contains a branch named 'baserock', that both contains a JSON configuration file
+defining how to build the chunk and any other changes required to get the
+repository to build with the rest of Baserock.
+.PP
+Morph is also capable of branching the whole system (that is branching all constituent
+git repositories of a system simultaneously) in order to allow system-wide changes that
+cross the boundaries of individual git repositories, and of generating commits to the
+group of git repositories that have been modified in such a branch.
+.PP
+For more details, please see the Baserock wiki at http://wiki.baserock.org.
.SH OPTIONS
.SH ENVIRONMENT
.B morph
@@ -87,7 +114,7 @@ sets the environment variable to
.TP
.B MORPH_PLUGIN_PATH
.B morph
-looks for plugins additionally in the directories given in this variable.
+looks for additional plugins in the directories given in this variable.
Syntax is same as for
.B PATH
(i.e., colon delimited pathnames).
@@ -97,9 +124,6 @@ The
manual page has some more variables that affect
.B morph
itself.
-.SH BUGS
-This manual page is badly incomplete,
-but at least it should include all options correctly.
.SH "SEE ALSO"
.BR cliapp (5).
.PP
--
1.7.9.5
10:26 a.m.
New subject: [PATCH] Modified man page to go into more detail about what morph does
A quick initial review. I'll continue this later.
On Fri, Aug 31, 2012 at 02:31:27PM +0100, Joel Dillon wrote:
+.B chunks
+, each of which in turn corresponds
This renders as "chunks ," -- to get "chunks," you need this markup:
.BR chunks ,
.SH "SEE ALSO"
.BR cliapp (5).
.PP
--
"SEE ALSO" should probably have a pointer to wiki.baserock.org
and www.baserock.com.
--
http://www.codethink.co.uk/
11:52 a.m.
New subject: [PATCH] Modified man page to go into more detail about what morph does
Troff tends to produce better formatted output if the source code
starts each new sentence on a new line. It's not worth rewriting
the patch for that, though, unless you've extra time.
On Fri, Aug 31, 2012 at 02:31:27PM +0100, Joel Dillon wrote:
+A chunk is a git repository based on an individual upstream
project's revision
+control system (converted into git if upstream does not already use it), which
+contains a branch named 'baserock', that both contains a JSON configuration file
+defining how to build the chunk and any other changes required to get the
+repository to build with the rest of Baserock.
Nitpick: There's no need for a chunk to contain any special branches. Any git
repo can work, as long as the automatic build rules built into morph work.
However, that may be going into too much detail.
Apart from these and my earlier remarks, I'm OK with this patch and happy
to see it merged into master.
--
http://www.codethink.co.uk/
12:12 p.m.
New subject: [PATCH] Modified man page to go into more detail about what morph does (updated based on review)
---
morph.1.in | 42 ++++++++++++++++++++++++++++++++++--------
1 file changed, 34 insertions(+), 8 deletions(-)
diff --git a/morph.1.in b/morph.1.in
index 38bff72..8148038 100644
--- a/morph.1.in
+++ b/morph.1.in
@@ -23,7 +23,35 @@ Baserock is an embedded Linux system.
is its workflow tool.
It manages building binaries,
and branching and merging of the entire system.
-See the Baserock home page for more information.
+Morph is designed to turn collections of git repositories into system images
+using morphology files to define their dependencies.
+.PP
+A
+.B system
+image is defined as a group of
+.B strata
+describing subsystems,
+each of which comprises a series of
+.B chunks,
+each of which in turn corresponds to an individual upstream project.
+For example, there might be a 'generic developer system' system morphology,
+containing a stratum for the basic bootable system and another for developer
+tools; the latter would then have individual chunks for make, gcc, binutils
+and so forth.
+.PP
+A chunk is a git repository based on an individual upstream project's revision
+control system (converted into git if upstream does not already use it), which
+either is compatible with morph's automatic build rules as is or contains a branch
named
+'baserock'; in the latter case this both contains a JSON configuration file
+defining how to build the chunk and any other changes required to get the
+repository to build with the rest of Baserock.
+.PP
+Morph is also capable of branching the whole system (that is branching all constituent
+git repositories of a system simultaneously) in order to allow system-wide changes that
+cross the boundaries of individual git repositories, and of generating commits to the
+group of git repositories that have been modified in such a branch.
+.PP
+For more details, please see the Baserock wiki at http://wiki.baserock.org.
.SH OPTIONS
.SH ENVIRONMENT
.B morph
@@ -87,7 +115,7 @@ sets the environment variable to
.TP
.B MORPH_PLUGIN_PATH
.B morph
-looks for plugins additionally in the directories given in this variable.
+looks for additional plugins in the directories given in this variable.
Syntax is same as for
.B PATH
(i.e., colon delimited pathnames).
@@ -97,10 +125,8 @@ The
manual page has some more variables that affect
.B morph
itself.
-.SH BUGS
-This manual page is badly incomplete,
-but at least it should include all options correctly.
.SH "SEE ALSO"
-.BR cliapp (5).
-.PP
-http://wiki.baserock.org/
+.BR cliapp (5),
+.B http://wiki.baserock.org/,
+.B http://www.baserock.com/.
+
--
1.7.9.5
12:42 p.m.
New subject: [PATCH] Modified man page to go into more detail about what morph does
On Fri, Aug 31, 2012 at 04:52:16PM +0100, Lars Wirzenius wrote:
Troff tends to produce better formatted output if the source code
starts each new sentence on a new line. It's not worth rewriting
the patch for that, though, unless you've extra time.
On Fri, Aug 31, 2012 at 02:31:27PM +0100, Joel Dillon wrote:
> +A chunk is a git repository based on an individual upstream project's revision
> +control system (converted into git if upstream does not already use it), which
> +contains a branch named 'baserock', that both contains a JSON configuration
file
> +defining how to build the chunk and any other changes required to get the
> +repository to build with the rest of Baserock.
Nitpick: There's no need for a chunk to contain any special branches. Any git
repo can work, as long as the automatic build rules built into morph work.
However, that may be going into too much detail.
Apart from these and my earlier remarks, I'm OK with this patch and happy
to see it merged into master.
I have now done the merge and pushed.
--
http://www.codethink.co.uk/
3934
days inactive
3934
days old
5 comments
2 participants
participants (2)
-
Joel Dillon -
Lars Wirzenius