Mercurial > hg > index.cgi

annotate 00README.txt @ 574:a0c9433dc0d4 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated submission guidelines including notes about evangelism. TLDR: Don't.
author William Astle <lost@l-w.ca>
date Mon, 04 Mar 2024 10:10:38 -0700
parents 4130ffdeb5c8
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
341
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
1 The official distribution point for lwtools is
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
2 http://lwtools.projects.l-w.ca/. If you obtained this distribution from any
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
3 other place, please visit the official site. You may have a modified or out
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
4 of date version.
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
5
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
6 This is LWTOOLS, a cross development system targetting the 6809 CPU.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
7
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
8 It consists of an assembler, lwasm, a linker, lwlink, and an archiver,
18
8eddaa2ab6c0 Added note about gnu make being suggested
lost@l-w.ca
parents: 0
diff changeset
9 lwar which should compile on any reasonably modern POSIX environment. If you
8eddaa2ab6c0 Added note about gnu make being suggested
lost@l-w.ca
parents: 0
diff changeset
10 have problems building, make sure you are using GNU make. Other make
8eddaa2ab6c0 Added note about gnu make being suggested
lost@l-w.ca
parents: 0
diff changeset
11 programs may work but GNU make is known to work.
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
12
361
4130ffdeb5c8 Add contributed support for building with Microsoft's compiler
William Astle <lost@l-w.ca>
parents: 341
diff changeset
13 There is some source code support for building with Microsoft's compiler on
4130ffdeb5c8 Add contributed support for building with Microsoft's compiler
William Astle <lost@l-w.ca>
parents: 341
diff changeset
14 Windows. However, this has been contributed by interested users and is not
4130ffdeb5c8 Add contributed support for building with Microsoft's compiler
William Astle <lost@l-w.ca>
parents: 341
diff changeset
15 well tested. Indeed, the primary maintainer has no access to such a system.
4130ffdeb5c8 Add contributed support for building with Microsoft's compiler
William Astle <lost@l-w.ca>
parents: 341
diff changeset
16
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
17 To see if a quick build will work, just type "make". If it works, you're
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
18 ready to go ahead with "make install". This will install in /usr/local/bin.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
19
176
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
20 If you feel adventurous, you can also run the test suite by running "make
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
21 test". However, be warned that it is likely not going to work unless you are
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
22 running on a fairly standard unix system with perl in /usr/bin/perl.
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
23
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
24 See docs/ for additional information.
322
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
25
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
26 CONTRIBUTING
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
27 ============
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
28
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
29 If you wish to contribute patches or code to lwtools, please keep the
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
30 following in mind.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
31
574
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
32 Evangelism
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
33 ----------
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
34
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
35 Any communication that includes evangelism for alternate revision control
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
36 systems, coding styles, development methodologies, or similar will be
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
37 deleted with all other contents ignored. So just don't do it and save
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
38 yourself and the project maintainers time.
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
39
322
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
40 Style
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
41 -----
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
42
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
43 The code formatting style must match the rest of the lwtools code. Code
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
44 submitted in the "1TBS" will be rejected out of hand. Attempts to convince
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
45 me to change my mind on this point will be routed to /dev/null at best and
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
46 likely met with extreme rudeness.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
47
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
48 C code should be formatted as follows:
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
49
574
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
50 * In general, match the formatting of the surrounding code, whether that
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
51 uses spaces or tabs. Otherwise, all indentation uses a single TAB
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
52 character for each step. That is a HARD tab, not a series of spaces. TABs
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
53 are assumed to be 4 characters though that will largely impact only lining
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
54 up comments and tabular code. If the actual formatting of the code is
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
55 critical, spaces may be used for that formatting but the actual initial
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
56 indentation of the lines MUST use TAB characters.
322
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
57 * The opening brace for a block appears on the line below the control
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
58 structure that introduces it. It appears lined up with the preceding line
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
59 and nothing else appears on the same line.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
60 * Closing braces appear on a line by themselves ordinarily. The exception is
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
61 the "while" keyword in a "do-while" statement appears on the same line as
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
62 the closing brace for the block.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
63 * Case labels are lined up with the enclosing block (one level back from the
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
64 code of the block). The same guideline applies for ordinarily labels.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
65 * No spaces surround parentheses, brackets, or the dot operator. No space
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
66 precedes a comma but a space should follow it. Other operators should
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
67 usually be surrounded by spaces. A space should separate a keyword from
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
68 any surrounding except for sizeof() which should be written like a
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
69 function call. There is no space between a function name and the start of
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
70 its parameter list.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
71
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
72 In general, study the existing source formatting and copy the style. This is
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
73 what you should do anyway and the above should not be required.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
74
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
75 For code accepted to the contrib/ hierarchy, application of the above coding
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
76 style may be less strict.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
77
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
78 Submitting
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
79 ----------
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
80
574
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
81 Any attempts to evangelize git or any other alternative revision control
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
82 system will be deleted with *all* other contents ignored.
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
83
322
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
84 When submitting code to lwtools, it should be submitted as a patch file (hg
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
85 diff or diff -u). DO NOT submit entire source files. Remember, others may be
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
86 working on changes, too, and your complete source files are difficult to
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
87 merge with such situations. By submitting complete source files, you are
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
88 making far more work for the maintainer and it is generally considered rude.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
89
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
90 Always specify what version of the source you based your patch on. If
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
91 possible, work off the default branch in the mercurial repository. At the
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
92 very least, make sure you are working with the most recent release.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
93
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
94 It is also worth checking with the maintainer before submitting a patch.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
95 There may be some reason why your pet feature is not present in the official
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
96 release.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
97
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
98 Finally, be prepared to receive a list of deficiencies or requests for
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
99 improvements or clarification of why or how you did something.