Difference between revisions of "Contributor Guide"
(15 intermediate revisions by the same user not shown) | |||
Line 16: | Line 16: | ||
* FreeM contributions must not use language features unavailable in C89 | * FreeM contributions must not use language features unavailable in C89 | ||
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible | * Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible | ||
− | * Contributions | + | * Contributions should be backwards compatible with gcc 2.95.3 (the oldest compiler we support) |
− | * Contributions | + | * Contributions should not break compiles on Sun <code>cc</code> or <code>clang</code> |
+ | |||
+ | For the last two guidelines, FreeM core developers will test your contributions and work with you to address any incompatibilities with these older compilers. We do not require every contributor to have access to every compiler. | ||
===Autotools=== | ===Autotools=== | ||
Line 40: | Line 42: | ||
==Submitting Changes Without CVS Write Access== | ==Submitting Changes Without CVS Write Access== | ||
− | To submit a change to FreeM as an anonymous user (i.e., a user without writer access to the FreeM CVS repository), generate a <code>.patch</code> file using the <code>diff</code> utility, and send it to <code>freem- | + | To submit a change to FreeM as an anonymous user (i.e., a user without writer access to the FreeM CVS repository), generate a <code>.patch</code> file using the <code>diff</code> utility, and send it to <code>freem-dev@mailman.chivanet.org</code> (you must be subscribed to the mailing list), along with a description containing the following information: |
* What bug your patch fixes, or feature it implements | * What bug your patch fixes, or feature it implements | ||
Line 116: | Line 118: | ||
$ cvs ci -m "commit-message" | $ cvs ci -m "commit-message" | ||
</pre> | </pre> | ||
+ | |||
+ | |||
+ | =Building FreeM= | ||
+ | |||
+ | Please see [[:Category:Platform Notes]] for any additional notes unique to your platform. | ||
+ | |||
+ | Note that the autotools <code>make install</code> will place FreeM in <code>/usr/local</code> by default on most platforms. This conflicts with binary packages on Solaris. | ||
+ | |||
+ | You can override the default installation location in the <code>configure</code> step with the following command: | ||
+ | |||
+ | <pre> | ||
+ | $ ./configure --prefix=/path/to/desired/location | ||
+ | </pre> | ||
+ | |||
+ | ==Initial Build== | ||
+ | This applies to the first build after you've obtained the FreeM source code. | ||
+ | |||
+ | Follow these steps for the initial build: | ||
+ | |||
+ | # Change directories to the <code>freem</code> repository | ||
+ | # Run <code>./autogen.sh</code> | ||
+ | # Run <code>./configure</code> | ||
+ | # Run <code>make</code> | ||
+ | # Run <code>sudo make install</code> | ||
+ | |||
+ | Once you have done the initial build, most changes shouldn't require more than a <code>make</code>. | ||
+ | |||
+ | ==Subsequent Builds== | ||
+ | Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats. | ||
+ | |||
+ | ===When to run autogen.sh=== | ||
+ | The <code>autogen.sh</code> script is currently a shorthand for <code>autoreconf --install</code>. | ||
+ | |||
+ | We recommend that FreeM hackers get used to using <code>autogen.sh</code> instead of running <code>autoreconf --install</code> directly, as <code>autogen.sh</code> may eventually contain other auto-generated items in future. | ||
+ | |||
+ | You will need to run <code>autogen.sh</code> only if you change any <code>configure.ac</code> or <code>Makefile.am</code> files. Even then, a fresh <code>make</code> will generally check to see if your generated autoconf/automake files are older than <code>configure.ac</code> or <code>Makefile.am</code> and do this step for you automatically. | ||
+ | |||
+ | ===When to run make install=== | ||
+ | You should only need to run <code>make install</code> in the following scenarios: | ||
+ | |||
+ | * You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work | ||
+ | * You've modified a vendor routine in the <code>mlib/</code> directory | ||
+ | * You've modified <code>libfreem</code> and want to test it from a standard system location | ||
+ | |||
+ | Other than these scenarios, you should be able to run the <code>freem</code> and <code>fmadm</code> binaries out of the repository directory hierarchy. |
Latest revision as of 16:32, 5 April 2025
Contents
Overview
This article describes the facilities, methods, and commands used to contribute to the FreeM project.
For All Developers
Overview
In order to contribute to FreeM, you must agree to abide by both the Code of Conduct and the General Policies. Your code must also conform to the style standards laid out in Appendix F of The FreeM Manual.
You will also need to have cvs
installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.
Language
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the mlib
routines.
C Standard
- FreeM contributions must not use language features unavailable in C89
- Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible
- Contributions should be backwards compatible with gcc 2.95.3 (the oldest compiler we support)
- Contributions should not break compiles on Sun
cc
orclang
For the last two guidelines, FreeM core developers will test your contributions and work with you to address any incompatibilities with these older compilers. We do not require every contributor to have access to every compiler.
Autotools
- Contributions to
autoconf
andautomake
configuration must not usepkg-config
, as it is unavailable on some of our target platforms - Target
autoconf
2.54 andautomake
1.7.1 for compatibility
Anonymous CVS Access
Getting Source Code from CVS
To fetch the latest FreeM source code from CVS, run the following command:
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem
Updating Your Copy of FreeM Source Code
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd
Submitting Changes Without CVS Write Access
To submit a change to FreeM as an anonymous user (i.e., a user without writer access to the FreeM CVS repository), generate a .patch
file using the diff
utility, and send it to freem-dev@mailman.chivanet.org
(you must be subscribed to the mailing list), along with a description containing the following information:
- What bug your patch fixes, or feature it implements
- Your full preferred name (this will be used in order to credit you for your work)
- Your preferred e-mail address
Each patch should address no more than one bug fix or feature addition. Patches that do not comply with this requirement will be kicked back to the developer for revision.
CVS Writer Access
Requesting Writer Access
In order to get CVS writer access, you will need to have either a track record of submitting good patches, or be an existing member of the core team. If you meet this criteria, please send a request to
freem-dev@mailman.chivanet.org
, including the following information:
- Your full preferred name
- Your preferred e-mail address
- The username you would like to use for access to our CVS server (we will do our best to accommodate, but you may be required to choose a different username if your preferred username is already taken)
Configuring CVS
Once the below changes are made, you will need to log out and log back in to make them take effect.
Bourne-Again Shell (bash)
In ~/.bashrc
or ~/.bash_profile
, add the following lines, substituting your cvs.coherent-logic.com
username for username:
export CVS_RSH=/usr/bin/ssh export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot
You may also need to change the CVS_RSH
value to the correct absolute path to your ssh
binary. You can find this information using which ssh
.
C Shell
In ~/.cshrc
, add the following lines, substituting your cvs.coherent-logic.com
username for username:
setenv CVS_RSH /usr/bin/ssh setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot
Fetching FreeM Source Code
To fetch the latest FreeM source code for the first time, run the following command:
$ cvs co freem
If this fails, make sure you have the CVS_RSH
and CVSROOT
environment variables correctly configured.
Updating Your Copy of FreeM Source Code
In the directory containing the FreeM source code, run the following command:
$ cvs update -Pd
Adding Files to the Repository
Run the following commands from the freem
directory, substituting the path and filename (relative to the freem
directory) for <filename>
:
$ cvs add <filename>
Committing Changes and Pushing to the Repository
Run the following commands from the parent directory of the freem
directory, replacing commit-message
with a message describing the change:
$ cvs ci -m "commit-message"
Building FreeM
Please see Category:Platform Notes for any additional notes unique to your platform.
Note that the autotools make install
will place FreeM in /usr/local
by default on most platforms. This conflicts with binary packages on Solaris.
You can override the default installation location in the configure
step with the following command:
$ ./configure --prefix=/path/to/desired/location
Initial Build
This applies to the first build after you've obtained the FreeM source code.
Follow these steps for the initial build:
- Change directories to the
freem
repository - Run
./autogen.sh
- Run
./configure
- Run
make
- Run
sudo make install
Once you have done the initial build, most changes shouldn't require more than a make
.
Subsequent Builds
Most subsequent builds will just need a make
. See the following paragraphs for caveats.
When to run autogen.sh
The autogen.sh
script is currently a shorthand for autoreconf --install
.
We recommend that FreeM hackers get used to using autogen.sh
instead of running autoreconf --install
directly, as autogen.sh
may eventually contain other auto-generated items in future.
You will need to run autogen.sh
only if you change any configure.ac
or Makefile.am
files. Even then, a fresh make
will generally check to see if your generated autoconf/automake files are older than configure.ac
or Makefile.am
and do this step for you automatically.
When to run make install
You should only need to run make install
in the following scenarios:
- You've changed the way the environment catalog (
env.conf
) or environment configuration files (freem.conf
) work - You've modified a vendor routine in the
mlib/
directory - You've modified
libfreem
and want to test it from a standard system location
Other than these scenarios, you should be able to run the freem
and fmadm
binaries out of the repository directory hierarchy.