<html lang='en'>
<head>
<meta content='text/html; charset=utf-8' http-equiv='Content-Type'>
<title>
GitLab
</title>
</meta>
</head>
<style>
img {
max-width: 100%;
height: auto;
}
p.details {
font-style:italic;
color:#777
}
.footer p {
font-size:small;
color:#777
}
pre.commit-message {
white-space: pre-wrap;
}
.file-stats a {
text-decoration: none;
}
.file-stats .new-file {
color: #090;
}
.file-stats .deleted-file {
color: #B00;
}
</style>
<body>
<div class='content'>
<h3>
Andrew Price pushed to branch master
at <a href="https://projects.sucs.org/arthur/mw">Justin Mitchell / mw</a>
</h3>
<h4>
Commits:
</h4>
<ul>
<li>
<strong><a href="https://projects.sucs.org/arthur/mw/commit/884eb210d78f260cb4e3efe3c4aa7e7ba68036ed">884eb210</a></strong>
<div>
<span>by Andrew Price</span>
<i>at 2016-03-05T02:36:47+00:00</i>
</div>
<pre class='commit-message'>Install files to the right place in 'make test'</pre>
</li>
<li>
<strong><a href="https://projects.sucs.org/arthur/mw/commit/52dd8a34c5accbb8bf4f27912b0ccaec59f12ffc">52dd8a34</a></strong>
<div>
<span>by Andrew Price</span>
<i>at 2016-03-05T04:13:10+00:00</i>
</div>
<pre class='commit-message'>Add a dummies guide to mw development
It's a bit stream-of-consciousness at the moment but I hope it will be
useful to help people get started.</pre>
</li>
</ul>
<h4>2 changed files:</h4>
<ul>
<li class='file-stats'>
<a href='#diff-0'>
<span class='new-file'>
+
HACKING
</span>
</a>
</li>
<li class='file-stats'>
<a href='#diff-1'>
src/Makefile
</a>
</li>
</ul>
<h4>Changes:</h4>
<li id='diff-0'>
<a href='https://projects.sucs.org/arthur/mw/compare/769ee045c751432f5edeeae67ff5f6055ac2b2ce...52dd8a34c5accbb8bf4f27912b0ccaec59f12ffc#diff-0'>
<strong>
HACKING
</strong>
</a>
<hr>
<pre class="highlight"><code><span style="color: #000000;background-color: #ffdddd">--- /dev/null
</span><span style="color: #000000;background-color: #ddffdd">+++ b/HACKING
</span><span style="color: #aaaaaa">@@ -0,0 +1,140 @@
</span><span style="color: #000000;background-color: #ddffdd">+
+ "It's easier to ask forgiveness than it is to get permission."
+ -- Grace Hopper
+
+ "It worked!"
+ -- J. Robert Oppenheimer
+
+
+ The Hitchhacker's Guide to Milliways Development
+ (To be read in the voice of Peter Jones)
+-------------------------------------------------
+This is the best and worst guide to Milliways testing and development ever
+written. It assumes that you are already familiar with git and know where to
+clone the mw repository from. Whether you use your own public clone and send a
+pull request, or you have permission to push to the main git tree, or use git
+format-patch and git send-email is largely academic as no single git workflow
+has been chosen (nor, more importantly, rejected). It also assumes that you're
+familiar with running and using mw and have a general sense of how it works, or
+at least a willingness to learn how it works for yourself.
+
+This guide should be kept updated to reflect changes in workflows and the build
+system, which is currently a strange tangle of context-sensitive GNU Make rules
+grown organically over time to support some unconventional requirements. If you
+find any problems with, or ways to improve this document, report a bug or
+send/push a patch.
+
+ The Condensed Version
+-----------------------
+ 1. git clone .../mw.git
+ 2. cd mw/src
+ 3. make test
+ 4. workworkwork...
+ 5. make test
+ 6. ./mwserv -f &
+ 7. ./mw
+ 8. testtesttest... !qq
+ 9. if fail, goto 4
+10. git add changed files...
+11. git commit
+
+ The Version Nobody Reads
+--------------------------
+The most difficult part of contributing to any open source project can be
+finding something to work on. Therefore, the most useful thing to do when
+starting out with a project (assuming you want to work on the code rather than
+the docs or other supporting material) is to increase your chances of
+triggering bugs. One way to do this with mw is to run your own test version, as
+your user, from the source directory, so that you can throw all sorts of crazy
+combinations of inputs at it without stepping on anyone's toes. It also means
+you can quickly test any changes in a tight develop-test cycle.
+
+To get started, first clone the git tree and change into the src subdirectory:
+
+ $ git clone .../mw.git
+ $ cd mw/src
+
+Then run the 'test' make rule, which first creates a directory (named mwtest by
+default) into which an appropriate directory structure and mw's static files
+(docs, banner, etc.) are installed. It then builds mw and mwserv, setting the
+appropriate hardcoded paths to the new directory by passing them as -D options
+to the compiler. [NB it would be useful and more flexible to add configuration
+options and/or command line options to provide the paths in future, to simplify
+or obsolete the separate 'test' rule.]
+
+ $ make test
+
+As of the time of writing, the Javascript library that mw uses is bundled in
+with the source tree and will be built the first time you run this command.
+This can take a while on a slow machine but it will only need to be done once
+unless the mozjs directory is cleaned.
+
+In order to build mw you will need the buid dependencies installed on your
+system. The best way to find out what these currently are is to look at the
+build requirements listed in the RPM spec file 'mw.spec' at the top of the
+source tree, or the debian-template/control file. You will also need basic
+toolchain packages like gcc, g++ and GNU Make installed.
+
+Now that you've completed your first mw build, you can run the 'mwserv' server
+and the 'mw' client programs.
+
+ $ ./mwserv
+
+A note on mwserv daemonization: by default, mwserv quietly 'daemonizes' itself
+by forking off and ending the parent process so that the child is not attached
+to your terminal. This means that you will have to kill it with 'pkill mwserv'
+or similar in order to shut it down. Alternatively, and better for testing,
+mwserv has a foreground mode which causes it to stay running in your terminal
+and also turns on useful debugging messages. This can be enabled using the
+--foreground or -f command line option, but if you intend to run mwserv often,
+you might prefer to create a ~/.mwserv.conf file and set the "foreground"
+option to true. To generate an initial .mwserv.conf file containing mwserv's
+default configuration, run ./mwserv -P which will print a JSON-formatted config
+similar to:
+
+ $ ./mwserv -P
+ {
+ "foreground": false,
+ "port": 9999,
+ "user": "mw"
+ }
+
+You can use this as the base for your ~/.mwserv.conf. You may also wish to
+change the port number, particularly if you are testing on a shared development
+machine, although this will mean you have to run the client (./mw) with the
+-server option. The "user" option is really only useful when mw has been
+deployed and is launched as the root user which will allow it to setuid() as
+the specified user. Once you've created this file, you can verify that mwserv
+will pick up your changes by running './mwserv -P' again. With mwserv
+configured to run in the foreground, run it with
+
+ $ ./mwserv &
+
+to send it into the background, or just run it in a separate terminal in the
+foreground, so that you can then run
+
+ $ ./mw
+
+and begin your testing.
+
+A note on mw's client/server status: mw started off as a peer-to-peer system
+which meant that all mw processes had to be run with permission to read and
+write the data files containing the BBS folder, messages, logs and user data.
+As the transition to client/server is still ongoing this is largely still the
+case, although much of the actual chat-related communication is now sent via a
+custom protocol over TCP/IP sockets. Details of the protocol can be found in
+the src/server/PROTOCOL file. After making changes and rebuilding with 'make
+test' you will need to make sure your previously running mwserv process has
+been killed before testing again.
+
+To remove all of the built files in the src directory and below you can run
+'make cleanall' in the src directory. This will leave your mwtest directory in
+place. To remove that too, run 'make testclean'.
+
+As a rule, the code that lives in the src directory is meant to be library code
+which is common to the client and the server. It gets compiled into a static
+libmw.a archive which makes it easier for the client and server to link against
+it. The code in the src/client/ and src/server/ directories are specific to the
+client and server respectively.
+
+// TODO: What else would be useful to include here?
</span></code></pre>
<br>
</li>
<li id='diff-1'>
<a href='https://projects.sucs.org/arthur/mw/compare/769ee045c751432f5edeeae67ff5f6055ac2b2ce...52dd8a34c5accbb8bf4f27912b0ccaec59f12ffc#diff-1'>
<strong>
src/Makefile
</strong>
</a>
<hr>
<pre class="highlight"><code><span style="color: #000000;background-color: #ffdddd">--- a/src/Makefile
</span><span style="color: #000000;background-color: #ddffdd">+++ b/src/Makefile
</span><span style="color: #aaaaaa">@@ -40,7 +40,7 @@ test testclean:
</span> $(MAKE) TESTDIR="$(CURDIR)/mwtest" $@
else
test:
<span style="color: #000000;background-color: #ffdddd">- $(MAKE) -C $(SRCROOT) DESTDIR="$(TESTDIR)" install-home
</span><span style="color: #000000;background-color: #ddffdd">+ $(MAKE) -C $(SRCROOT) libdir="$(TESTDIR)" localstatedir="$(TESTDIR)" install-home
</span> cd "$(TESTDIR)" && mkdir -p mw run/mw log/mw lib/mw
$(MAKE) libdir="$(TESTDIR)" localstatedir="$(TESTDIR)" all
$(MAKE) -C utils libdir="$(TESTDIR)" localstatedir="$(TESTDIR)" all
</code></pre>
<br>
</li>
</div>
<div class='footer' style='margin-top: 10px;'>
<p>
—
<br>
<a href="https://projects.sucs.org/arthur/mw/compare/769ee045c751432f5edeeae67ff5f6055ac2b2ce...52dd8a34c5accbb8bf4f27912b0ccaec59f12ffc">View it on GitLab</a>.
<br>
You're receiving this email because of your account on projects.sucs.org.
If you'd like to receive fewer emails, you can
adjust your notification settings.
</p>
</div>
</body>
</html>