https://freem-wiki.coherent-logic.com/api.php?action=feedcontributions&feedformat=atom&user=SmwFreeM Wiki - User contributions [en]2026-04-18T10:10:16ZUser contributionsMediaWiki 1.34.4https://freem-wiki.coherent-logic.com/index.php?title=Main_Page&diff=408Main Page2025-05-16T13:05:16Z<p>Smw: </p>
<hr />
<div>This wiki contains documentation not included in the [https://freem.coherent-logic.com/docs FreeM Manual], including platform-specific installation and configuration notes, project policies, technical deep-dives, and release notes.<br />
<br />
== Release Notes ==<br />
* [[Conformance Clause]]<br />
* [[FreeM 0.62.3]]<br />
* [[FreeM 0.62.2]]<br />
* [[FreeM 0.62.1]]<br />
* [[FreeM Lite]]<br />
* [[FreeM 0.59.2]]<br />
<br />
== Project Policies and Procedures ==<br />
* [[General Policies]]<br />
* [[Code of Conduct]]<br />
<br />
== Hacking FreeM Code ==<br />
* [[Contributor Guide]]<br />
* [[Release Procedure]]<br />
<br />
== Port Tiers ==<br />
* [[Port Tiers]]<br />
* [[:Category:Tier 1 Ports|Tier 1 Ports]]<br />
* [[:Category:Tier 2 Ports|Tier 2 Ports]]<br />
* [[:Category:Tier 3 Ports|Tier 3 Ports]]<br />
<br />
== Platform Notes ==<br />
=== Tier 1 Ports ===<br />
* [[Platform Notes (Solaris/Illumos)]]<br />
* [[Platform Notes (NetBSD)]]<br />
* [[Platform Notes (FreeBSD)]]<br />
* [[Platform Notes (GNU/Linux)]]<br />
* [[Platform Notes (OpenBSD)]]<br />
<br />
=== Tier 2 Ports ===<br />
* [[Platform Notes (OS/2)]]<br />
* [[Platform Notes (SCO OpenServer)]]<br />
* [[Platform Notes (Compaq Tru64 UNIX)]]<br />
* [[Platform Notes (IBM AIX)]]<br />
* [[Platform Notes (Mac OS X)]]<br />
<br />
=== Tier 3 Ports ===<br />
* [[Platform Notes (GNU HURD)]]<br />
* [[Platform Notes (SGI IRIX)]]<br />
* [[Platform Notes (HP-UX)]]<br />
* [[Platform Notes (Minix 3+)]]<br />
<br />
== Tips and Tricks ==<br />
* [[Subscript Rules (Local and Global)]]<br />
* [[Object-Oriented Programming in FreeM]]<br />
<br />
== Technical Deep-Dives ==<br />
* [[FreeM System Architecture]]<br />
* [[Event Handling in FreeM]]<br />
* [[FreeM Transaction Processing Architecture]]<br />
* [[What is the GUMP?]]<br />
* [[Namespace Rules]]<br />
* [[Routine and Global Search Path Internals]]<br />
<br />
== History ==<br />
* [[FreeM History]]<br />
* [[Original README from Shalom ha-Ashkenaz]]<br />
<br />
== Status of Popular M Applications in FreeM ==<br />
<br />
* [[Applications: VA VistA]]<br />
* [[Applications: VA FileMan]]<br />
* [[Applications: VPE (Victory Programming Environment)]]<br />
* [[Applications: M Web Server]]<br />
* [[Applications: GDS/JDS]]<br />
* [[Applications: MVTS (M Validation and Test Suite)]]<br />
<br />
== General M Topics ==<br />
* [[M User's Group]]<br />
* [[M Technology Association]]<br />
* [[M Development Committee]]<br />
* [[Cache and M Technology Association UK]]<br />
* [[M User's Group-Deutschland]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(Mac_OS_X)&diff=407Platform Notes (Mac OS X)2025-05-16T13:02:19Z<p>Smw: /* Port Challenges */</p>
<hr />
<div>== Port Status ==<br />
<br />
The Mac OS X port is a [[Tier 2 Port]].<br />
The main branch will compile on macOS Monterey (12.6.8) on Intel, and it can run if the <code>kern.sysv.shmmax</code> parameter is correct (see below).<br />
<br />
== Verified Releases ==<br />
* [[FreeM Lite]]<br />
* FreeM 0.65.1-rc0<br />
<br />
== Build Notes ==<br />
<br />
In order to build FreeM on macOS, you will need to install the following:<br />
<br />
* Apple XCode command-line tools<br />
* Homebrew<br />
<br />
Then, install the following with the brew package manager:<br />
<br />
* automake<br />
* autoconf<br />
* gcc<br />
* libtool<br />
* texinfo<br />
* texi2html<br />
* git<br />
<br />
== Testing Details ==<br />
<br />
We build the macOS port on the following hardware:<br />
<br />
* MacBook Air (Early 2015) running macOS Monterey (12.6.8)<br />
* M1 Mac Mini running macOS Sequoia<br />
<br />
== Required Kernel Tuning ==<br />
<br />
You will need to set the <code>kern.sysv.shmmax</code> sysctl parameter to at least 17002496 (the value must be a multiple of the system page size; generally 4096).<br />
<br />
To determine the current setting, see below:<br />
<br />
<pre><br />
$ sudo sysctl -a | grep shmmax<br />
kern.sysv.shmmax: 4194304<br />
</pre><br />
<br />
In the above example, the <code>shmmax</code> value is <code>4194304</code>, and thus insufficient for proper FreeM operation.<br />
<br />
See your macOS version below for instructions on modifying this value.<br />
<br />
=== All Versions ===<br />
<br />
* Find the file <code>com.startup.sysctl.plist</code> file in the <code>scripts</code> subdirectory of the FreeM distribution<br />
* Copy it to <code>/Library/LaunchDaemons</code><br />
* Change the ownership of <code>/Library/LaunchDaemons/com.startup.sysctl.plist</code> to <code>root:wheel</code><br />
* Run <code>sudo launchctl load /Library/LaunchDaemons/com.startup.sysctl.plist</code><br />
* Reboot<br />
<br />
See the following example:<br />
<br />
<pre><br />
$ sudo cp scripts/com.startup.sysctl.plist /Library/LaunchDaemons/<br />
$ sudo chown root:wheel /Library/LaunchDaemons/com.startup.sysctl.plist<br />
$ sudo launchctl load /Library/LaunchDaemons/com.startup.sysctl.plist<br />
</pre><br />
<br />
<br />
== Starting the FreeM Daemon Automatically ==<br />
Coming soon.<br />
<br />
== Port Challenges ==<br />
The shared memory architecture of FreeM had to be rewritten to support Apple's System V IPC changes for their Unified Memory Architecture.<br />
<br />
<br />
[[Category:Platform Notes]]<br />
[[Category:Tier 2 Ports]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(Mac_OS_X)&diff=406Platform Notes (Mac OS X)2025-05-16T13:01:38Z<p>Smw: </p>
<hr />
<div>== Port Status ==<br />
<br />
The Mac OS X port is a [[Tier 2 Port]].<br />
The main branch will compile on macOS Monterey (12.6.8) on Intel, and it can run if the <code>kern.sysv.shmmax</code> parameter is correct (see below).<br />
<br />
== Verified Releases ==<br />
* [[FreeM Lite]]<br />
* FreeM 0.65.1-rc0<br />
<br />
== Build Notes ==<br />
<br />
In order to build FreeM on macOS, you will need to install the following:<br />
<br />
* Apple XCode command-line tools<br />
* Homebrew<br />
<br />
Then, install the following with the brew package manager:<br />
<br />
* automake<br />
* autoconf<br />
* gcc<br />
* libtool<br />
* texinfo<br />
* texi2html<br />
* git<br />
<br />
== Testing Details ==<br />
<br />
We build the macOS port on the following hardware:<br />
<br />
* MacBook Air (Early 2015) running macOS Monterey (12.6.8)<br />
* M1 Mac Mini running macOS Sequoia<br />
<br />
== Required Kernel Tuning ==<br />
<br />
You will need to set the <code>kern.sysv.shmmax</code> sysctl parameter to at least 17002496 (the value must be a multiple of the system page size; generally 4096).<br />
<br />
To determine the current setting, see below:<br />
<br />
<pre><br />
$ sudo sysctl -a | grep shmmax<br />
kern.sysv.shmmax: 4194304<br />
</pre><br />
<br />
In the above example, the <code>shmmax</code> value is <code>4194304</code>, and thus insufficient for proper FreeM operation.<br />
<br />
See your macOS version below for instructions on modifying this value.<br />
<br />
=== All Versions ===<br />
<br />
* Find the file <code>com.startup.sysctl.plist</code> file in the <code>scripts</code> subdirectory of the FreeM distribution<br />
* Copy it to <code>/Library/LaunchDaemons</code><br />
* Change the ownership of <code>/Library/LaunchDaemons/com.startup.sysctl.plist</code> to <code>root:wheel</code><br />
* Run <code>sudo launchctl load /Library/LaunchDaemons/com.startup.sysctl.plist</code><br />
* Reboot<br />
<br />
See the following example:<br />
<br />
<pre><br />
$ sudo cp scripts/com.startup.sysctl.plist /Library/LaunchDaemons/<br />
$ sudo chown root:wheel /Library/LaunchDaemons/com.startup.sysctl.plist<br />
$ sudo launchctl load /Library/LaunchDaemons/com.startup.sysctl.plist<br />
</pre><br />
<br />
<br />
== Starting the FreeM Daemon Automatically ==<br />
Coming soon.<br />
<br />
== Port Challenges ==<br />
Apple makes it extremely difficult to build traditional UNIX software, in the name of "security". Also, Apple silicon (M1 and descendants) cannot likely be supported with the current shared memory architecture.<br />
<br />
We will most likely support only PowerPC and Intel Macs.<br />
<br />
[[Category:Platform Notes]]<br />
[[Category:Tier 2 Ports]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Conformance_Clause&diff=405Conformance Clause2025-05-05T04:50:19Z<p>Smw: </p>
<hr />
<div>== Conformance Policy ==<br />
<br />
FreeM attempts to comply with ANSI X11.1-1995 and the unpublished Millennium Draft Standard (MDS) from the [[M Development Committee]], in routine buffers where the dialect setting is set to a particular version of the standard.<br />
<br />
Routine buffers in <code>FREEM</code> dialect enable all nonstandard extensions.<br />
<br />
This article has been superseded by <code>freem_conformance(1)</code> in the UNIX manual.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=404Contributor Guide2025-04-29T22:30:49Z<p>Smw: /* Building FreeM */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions should be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions should not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
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.<br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
# Create a <code>freem</code> group<br />
# Create a <code>freem</code> user<br />
# Run <code>sudo fmadm configure</code><br />
<br />
You will need to add any users who will use FreeM to the <code>freem</code> group, and log out and back in.<br />
<br />
Once this is done, check the [[:Category:Platform Notes]] for your platform for further instructions about configuring your environment.<br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is currently a shorthand for <code>autoreconf --install</code>. <br />
<br />
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.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
* You've modified <code>libfreem</code> and want to test it from a standard system location<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=403Contributor Guide2025-04-29T22:24:56Z<p>Smw: /* Initial Build */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions should be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions should not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
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.<br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
# Create a <code>freem</code> group<br />
# Create a <code>freem</code> user<br />
# Run <code>sudo fmadm configure</code><br />
<br />
You will need to add any users who will use FreeM to the <code>freem</code> group, and log out and back in.<br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is currently a shorthand for <code>autoreconf --install</code>. <br />
<br />
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.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
* You've modified <code>libfreem</code> and want to test it from a standard system location<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=402Contributor Guide2025-04-29T22:23:14Z<p>Smw: </p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions should be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions should not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
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.<br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
# Create a <code>freem</code> group<br />
# Create a <code>freem</code> user<br />
# Run <code>sudo fmadm configure</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is currently a shorthand for <code>autoreconf --install</code>. <br />
<br />
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.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
* You've modified <code>libfreem</code> and want to test it from a standard system location<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(Solaris/Illumos)&diff=401Platform Notes (Solaris/Illumos)2025-04-16T00:08:38Z<p>Smw: /* Solaris 8 */</p>
<hr />
<div>== Port Category ==<br />
<br />
The Solaris port is a [[Tier 1 Port]], and Solaris 8 on 64-bit SPARC is the platform where primary development occurs.<br />
<br />
== Verified Releases ==<br />
* 0.62.3 (Solaris 5.8 sparc64, Solaris 5.10 i86pc, Solaris 5.11 i86pc, Solaris 5.11 sparc64, OpenIndiana Hipster 5.11 amd64, 27 Mar 2025<br />
* 0.62.2 (Solaris 5.8 sparc64, Solaris 5.10 i86pc, Solaris 5.11 i86pc, Solaris 5.11 sparc64, OpenIndiana Hipster 5.11 amd64, 23 Mar 2025)<br />
* 0.62.1 (Solaris 5.10 i86pc, 17 Mar 2025)<br />
* <code>cvs-current</code> (Solaris 5.8 sparc64, Solaris 11.4 sparc64 and i86pc)<br />
* 0.62.1 (Solaris 5.8 sparc64, Solaris 11.4 sparc64 and i86pc, OpenIndiana Hipster, 16 Mar 2025)<br />
* 0.61.2 (Solaris 5.8 sparc64, Solaris 11.4 sparc64 and i86pc)<br />
* 0.59.0 (Solaris 10 sparc64, 4 Aug 2023)<br />
* 0.59.0 (Solaris 7 sparc32, 4 Aug 2023)<br />
* 0.59.0 (Solaris 11.4 i86pc, 4 Aug 2023)<br />
* 0.57.0 (Solaris 11.3 sparc64, 4 Aug 2023)<br />
<br />
== Build Notes ==<br />
=== Solaris 7 ===<br />
* If using the old <code>sunfreeware.com</code> GNU toolchain packages on Solaris 7, you will need the latest <code>7_Recommended.zip</code> patch cluster.<br />
* The <code>mktemp</code> utility may lock up several times during the <code>configure</code> phase. If this happens, you may simply kill the process with <code>pkill -9 mktemp</code>. This does not appear to harm the build.<br />
<br />
=== Solaris 8 ===<br />
<br />
==== Binary Packages ====<br />
On Solaris 8, you can install a binary release:<br />
<br />
<pre><br />
$ sudo pkgadd -d CLDfreem-<version>-solaris5.8-sparcv9.pkg<br />
</pre><br />
<br />
Once this is done, add yourself to the <code>freem</code> group:<br />
# Open <code>/etc/group</code> as <code>root</code> in your favorite text editor<br />
# Find the line beginning with <code>freem</code><br />
# Append your username to the end of that line<br />
# Save the file<br />
# Exit the editor<br />
<br />
Now, you can start the FreeM daemon as follows:<br />
<br />
<pre><br />
$ sudo /etc/init.d/freem start<br />
</pre><br />
<br />
==== Building From Source ====<br />
You will need the latest <code>8_Recommended.zip</code> patch cluster for Solaris, as well as:<br />
<br />
* gcc (3.4 or higher recommended)<br />
* autoconf<br />
* automake<br />
* libtool<br />
* texinfo<br />
* readline (recommended but not strictly required)<br />
<br />
=== Solaris 9 ===<br />
TBD<br />
<br />
=== Solaris 10 ===<br />
TBD<br />
<br />
=== Solaris 11 ===<br />
We build with the IPS packages for the GNU toolchain here. The Sun C compiler can also be used here (at least the version from Developer Studio 12.6).<br />
<br />
==== Necessary Packages ====<br />
<code><br />
$ sudo pkg install gcc automake autoconf gnu-make git readline libtool texinfo ncurses<br />
</code><br />
<br />
==== Dealing with ncurses ====<br />
You will need to tell the configure script not to bother with the wide-character ncurses library (does not apply to releases later than 0.61.2):<br />
<br />
<code><br />
$ ./configure --without-ncursesw<br />
</code><br />
<br />
=== OpenIndiana ===<br />
==== Binary Packages ====<br />
On OpenIndiana, you can install a binary release:<br />
<br />
<pre><br />
$ sudo pkgadd -d CLDfreem-<version>-openindiana5.11-amd64.pkg<br />
</pre><br />
<br />
Once this is done, add yourself to the <code>freem</code> group, and start the FreeM daemon as follows:<br />
<br />
<pre><br />
$ sudo /etc/init.d/freem start<br />
</pre><br />
==== Building From Source ====<br />
See instructions for [[#Solaris 11|Solaris 11]], but with the exception that <code>configure</code> must be run as follows:<br />
<pre><br />
$ ./configure MAKE=gmake<br />
</pre><br />
<br />
== Testing Details ==<br />
<br />
We build and test the Solaris port of FreeM on the following systems:<br />
<br />
=== Sun Ultra 10 ===<br />
<br />
* Sun Ultra 10 with a 400MHz UltraSPARC-IIi CPU (64-bit)<br />
* 640MB RAM<br />
* Solaris 5.8 Generic_117350-39<br />
* gcc v3.4.6<br />
* autoconf 2.69<br />
* automake 1.16.5<br />
<br />
=== Sun SPARCserver 20 ===<br />
<br />
* Sun SPARCserver 20 with dual 100MHz Ross HyperSPARC CPUs (32-bit)<br />
* 512MB RAM<br />
* Solaris 7 with the latest 7_Recommended.zip patch cluster applied (REQUIRED FOR SOLARIS 7)<br />
* gcc v3.4.6<br />
* autoconf 2.68<br />
* automake 1.11.1<br />
<br />
=== SunFire T2000 ===<br />
<br />
* Sun UltraSPARC T1 CPU (64-bit)<br />
* Solaris 10<br />
<br />
=== Oracle SPARC T4-1 ===<br />
* Oracle SPARC T4 CPU (64-bit)<br />
* Solaris 11.4 11.4.0.15.0<br />
* gcc v7.3.0<br />
* autoconf 2.69<br />
* automake 1.15<br />
* Oracle Developer Studio 12.6 (SunCC compiler)<br />
<br />
=== x86 VM ===<br />
* Solaris 11.4 11.4.0.15.0<br />
* gcc v7.3.0<br />
* autoconf 2.69<br />
* automake 1.15<br />
<br />
=== OpenIndiana (Illumos) ===<br />
<br />
* Proxmox VM<br />
* OpenIndiana Hipster 5.11 illumos-053feb1540<br />
* gcc 14.2.0<br />
* autoconf 2.72<br />
* automake 1.16.5<br />
<br />
<br />
This port should theoretically run on any Solaris or Illumos machine running Solaris 7 or newer.<br />
<br />
== Required Kernel Tuning ==<br />
<br />
=== Solaris 11 ===<br />
TBD<br />
<br />
=== Solaris 8 ===<br />
Append the following to <code>/etc/system</code> and reboot:<br />
<br />
<pre><br />
set shmsys:shminfo_shmmax = 67108864 <br />
set shmsys:shminfo_shmmni = 0x1000<br />
set shmsys:shminfo_shmseg = 0x100<br />
</pre><br />
<br />
== Starting FreeM Daemon Automatically ==<br />
<br />
These instructions apply only to source builds. The binary packages install the init script automatically.<br />
<br />
* Copy <code>scripts/solaris-init/freem</code> to <code>/etc/init.d</code><br />
* Make a symbolic link from <code>/etc/rc3.d/S20freem</code> to <code>/etc/init.d/freem</code><br />
* Run <code>/etc/init.d/freem start</code><br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(FreeBSD)&diff=400Platform Notes (FreeBSD)2025-04-16T00:00:53Z<p>Smw: /* Address Space Layout Randomization */</p>
<hr />
<div>== Port Status ==<br />
FreeBSD is a [[Tier 1 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM 0.62.2 (23 Mar 2025)<br />
* FreeM <code>cvs-current</code><br />
* FreeM 0.62.1<br />
<br />
== Testing Details ==<br />
* Bare-metal amd64 system<br />
* FreeBSD 14.1-RELEASE-p2 amd64<br />
* gcc 13.2.0<br />
* autoconf 2.72<br />
* automake 1.17<br />
<br />
== Required Kernel Tuning ==<br />
=== Shared Memory ===<br />
FreeM in its default configuration requires just under 17MiB of shared memory. You can check the relevant kernel parameter with the following command:<br />
<br />
<pre><br />
$ sudo sysctl kern.ipc.shmmax<br />
</pre><br />
<br />
If <code>kern.ipc.shmmax</code> is less than <code>17000000</code>, add the following lines to <code>/etc/sysctl.conf</code> and reboot:<br />
<br />
<pre><br />
kern.ipc.shmmax=17000000<br />
</pre><br />
<br />
=== Address Space Layout Randomization ===<br />
FreeM is incompatible with address space layout randomization (ASLR), which is enabled by default on FreeBSD 13.2 and newer on 64-bit platforms.<br />
<br />
To use FreeM on FreeBSD 13.2 and newer, add the following lines to <code>/etc/sysctl.conf</code> and reboot:<br />
<br />
<pre><br />
kern.elf64.aslr.pie_enable=0<br />
kern.elf64.aslr.enable=0<br />
</pre><br />
<br />
If you do not wish to globally disable ASLR on your system, you can use FreeM by disabling it per-process with each invocation by using the following syntax:<br />
<br />
<pre><br />
$ proccontrol -m aslr -s disable freem<br />
</pre><br />
<br />
Particularly astute system administrators will likely want to script this, which is an exercise left to the reader.<br />
<br />
== Starting Daemon Automatically ==<br />
* Copy <code>scripts/freebsd-rc/freem</code> to <code>/usr/local/etc/rc.d</code><br />
* Type the following commands with root privileges:<br />
# pw group add freem<br />
# pw user add freem -m -g freem<br />
# sysrc freem_enable="YES"<br />
# chmod +x /usr/local/etc/rc.d/freem<br />
* For each user who needs to run FreeM, type the following command:<br />
# pw group mod freem -m ''username''<br />
* Reboot <br />
<br />
== Port Challenges ==<br />
None.<br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(FreeBSD)&diff=399Platform Notes (FreeBSD)2025-04-15T23:58:22Z<p>Smw: /* Address Space Layout Randomization */</p>
<hr />
<div>== Port Status ==<br />
FreeBSD is a [[Tier 1 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM 0.62.2 (23 Mar 2025)<br />
* FreeM <code>cvs-current</code><br />
* FreeM 0.62.1<br />
<br />
== Testing Details ==<br />
* Bare-metal amd64 system<br />
* FreeBSD 14.1-RELEASE-p2 amd64<br />
* gcc 13.2.0<br />
* autoconf 2.72<br />
* automake 1.17<br />
<br />
== Required Kernel Tuning ==<br />
=== Shared Memory ===<br />
FreeM in its default configuration requires just under 17MiB of shared memory. You can check the relevant kernel parameter with the following command:<br />
<br />
<pre><br />
$ sudo sysctl kern.ipc.shmmax<br />
</pre><br />
<br />
If <code>kern.ipc.shmmax</code> is less than <code>17000000</code>, add the following lines to <code>/etc/sysctl.conf</code> and reboot:<br />
<br />
<pre><br />
kern.ipc.shmmax=17000000<br />
</pre><br />
<br />
=== Address Space Layout Randomization ===<br />
FreeM is incompatible with address space layout randomization (ASLR), which is enabled by default on FreeBSD 13.2 and newer on 64-bit platforms.<br />
<br />
To use FreeM on FreeBSD 13.2 and newer, add the following lines to <code>/etc/sysctl.conf</code> and reboot:<br />
<br />
<pre><br />
kern.elf64.aslr.pie_enable=0<br />
kern.elf64.aslr.enable=0<br />
</pre><br />
<br />
If you do not wish to globally disable ASLR on your system, you can use FreeM by disabling it per-process with each invocation by using the following syntax:<br />
<br />
<pre><br />
$ proccontrol -m aslr -s disable freem<br />
</pre><br />
<br />
== Starting Daemon Automatically ==<br />
* Copy <code>scripts/freebsd-rc/freem</code> to <code>/usr/local/etc/rc.d</code><br />
* Type the following commands with root privileges:<br />
# pw group add freem<br />
# pw user add freem -m -g freem<br />
# sysrc freem_enable="YES"<br />
# chmod +x /usr/local/etc/rc.d/freem<br />
* For each user who needs to run FreeM, type the following command:<br />
# pw group mod freem -m ''username''<br />
* Reboot <br />
<br />
== Port Challenges ==<br />
None.<br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(FreeBSD)&diff=398Platform Notes (FreeBSD)2025-04-15T23:57:36Z<p>Smw: </p>
<hr />
<div>== Port Status ==<br />
FreeBSD is a [[Tier 1 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM 0.62.2 (23 Mar 2025)<br />
* FreeM <code>cvs-current</code><br />
* FreeM 0.62.1<br />
<br />
== Testing Details ==<br />
* Bare-metal amd64 system<br />
* FreeBSD 14.1-RELEASE-p2 amd64<br />
* gcc 13.2.0<br />
* autoconf 2.72<br />
* automake 1.17<br />
<br />
== Required Kernel Tuning ==<br />
=== Shared Memory ===<br />
FreeM in its default configuration requires just under 17MiB of shared memory. You can check the relevant kernel parameter with the following command:<br />
<br />
<pre><br />
$ sudo sysctl kern.ipc.shmmax<br />
</pre><br />
<br />
If <code>kern.ipc.shmmax</code> is less than <code>17000000</code>, add the following lines to <code>/etc/sysctl.conf</code> and reboot:<br />
<br />
<pre><br />
kern.ipc.shmmax=17000000<br />
</pre><br />
<br />
=== Address Space Layout Randomization ===<br />
FreeM is incompatible with address space layout randomization (ASLR), which is enabled by default on FreeBSD 13.2 and newer on 64-bit platforms.<br />
<br />
To use FreeM on FreeBSD 13 and newer, add the following lines to <code>/etc/sysctl.conf</code> and reboot:<br />
<br />
<pre><br />
kern.elf64.aslr.pie_enable=0<br />
kern.elf64.aslr.enable=0<br />
</pre><br />
<br />
If you do not wish to globally disable ASLR on your system, you can use FreeM by disabling it per-process with each invocation by using the following syntax:<br />
<br />
<pre><br />
$ proccontrol -m aslr -s disable freem<br />
</pre><br />
<br />
== Starting Daemon Automatically ==<br />
* Copy <code>scripts/freebsd-rc/freem</code> to <code>/usr/local/etc/rc.d</code><br />
* Type the following commands with root privileges:<br />
# pw group add freem<br />
# pw user add freem -m -g freem<br />
# sysrc freem_enable="YES"<br />
# chmod +x /usr/local/etc/rc.d/freem<br />
* For each user who needs to run FreeM, type the following command:<br />
# pw group mod freem -m ''username''<br />
* Reboot <br />
<br />
== Port Challenges ==<br />
None.<br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(FreeBSD)&diff=397Platform Notes (FreeBSD)2025-04-15T23:53:55Z<p>Smw: /* Address Space Layout Randomization */</p>
<hr />
<div>== Port Status ==<br />
FreeBSD is a [[Tier 1 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM 0.62.2 (23 Mar 2025)<br />
* FreeM <code>cvs-current</code><br />
* FreeM 0.62.1<br />
<br />
== Testing Details ==<br />
* Bare-metal amd64 system<br />
* FreeBSD 14.1-RELEASE-p2 amd64<br />
* gcc 13.2.0<br />
* autoconf 2.72<br />
* automake 1.17<br />
<br />
== Required Kernel Tuning ==<br />
<br />
=== Address Space Layout Randomization ===<br />
FreeM is incompatible with address space layout randomization (ASLR), which is enabled by default on FreeBSD 13.2 and newer on 64-bit platforms.<br />
<br />
To use FreeM on FreeBSD 13 and newer, add the following lines to <code>/etc/sysctl.conf</code> and reboot:<br />
<br />
<pre><br />
kern.elf64.aslr.pie_enable=0<br />
kern.elf64.aslr.enable=0<br />
</pre><br />
<br />
If you do not wish to globally disable ASLR on your system, you can use FreeM by disabling it per-process with each invocation by using the following syntax:<br />
<br />
<pre><br />
$ proccontrol -m aslr -s disable freem<br />
</pre><br />
<br />
== Starting Daemon Automatically ==<br />
* Copy <code>scripts/freebsd-rc/freem</code> to <code>/usr/local/etc/rc.d</code><br />
* Type the following commands with root privileges:<br />
# pw group add freem<br />
# pw user add freem -m -g freem<br />
# sysrc freem_enable="YES"<br />
# chmod +x /usr/local/etc/rc.d/freem<br />
* For each user who needs to run FreeM, type the following command:<br />
# pw group mod freem -m ''username''<br />
* Reboot <br />
<br />
== Port Challenges ==<br />
None.<br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(FreeBSD)&diff=396Platform Notes (FreeBSD)2025-04-15T23:52:36Z<p>Smw: /* Required Kernel Tuning */</p>
<hr />
<div>== Port Status ==<br />
FreeBSD is a [[Tier 1 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM 0.62.2 (23 Mar 2025)<br />
* FreeM <code>cvs-current</code><br />
* FreeM 0.62.1<br />
<br />
== Testing Details ==<br />
* Bare-metal amd64 system<br />
* FreeBSD 14.1-RELEASE-p2 amd64<br />
* gcc 13.2.0<br />
* autoconf 2.72<br />
* automake 1.17<br />
<br />
== Required Kernel Tuning ==<br />
<br />
=== Address Space Layout Randomization ===<br />
FreeM shared memory is incompatible with address space layout randomization on FreeBSD 13 and newer.<br />
<br />
To use FreeM on FreeBSD 13 and newer, add the following lines to <code>/etc/sysctl.conf</code> and reboot:<br />
<br />
<pre><br />
kern.elf64.aslr.pie_enable=0<br />
kern.elf64.aslr.enable=0<br />
</pre><br />
<br />
If you do not wish to globally disable ASLR on your system, you can use FreeM by disabling it per-process with each invocation by using the following syntax:<br />
<br />
<pre><br />
$ proccontrol -m aslr -s disable freem<br />
</pre><br />
<br />
== Starting Daemon Automatically ==<br />
* Copy <code>scripts/freebsd-rc/freem</code> to <code>/usr/local/etc/rc.d</code><br />
* Type the following commands with root privileges:<br />
# pw group add freem<br />
# pw user add freem -m -g freem<br />
# sysrc freem_enable="YES"<br />
# chmod +x /usr/local/etc/rc.d/freem<br />
* For each user who needs to run FreeM, type the following command:<br />
# pw group mod freem -m ''username''<br />
* Reboot <br />
<br />
== Port Challenges ==<br />
None.<br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(OS/2)&diff=395Platform Notes (OS/2)2025-04-10T16:56:16Z<p>Smw: </p>
<hr />
<div>== Port Status ==<br />
OS/2 is a [[Tier 2 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.64.0-rc0 (10 Apr 2025)<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM cvs-current (23 Mar 2025)<br />
<br />
== Testing Details ==<br />
We build and test the OS/2 port on an ArcaOS 5.1 VM running in VirtualBox.<br />
<br />
== Building and Installing ==<br />
Currently, the OS/2 port is only tested on ArcaOS, and you will need to install several things in order to build and run:<br />
<br />
* autoconf<br />
* automake<br />
* gcc<br />
* readline-devel<br />
* bash<br />
* binutils-devel<br />
* coreutils<br />
* emxrt<br />
* gawk<br />
* gcc-wlink<br />
* gcc-wrt<br />
* grep<br />
* info<br />
* libc-devel<br />
* libtool<br />
* kbuild-make<br />
* sed<br />
* tar<br />
* gzip<br />
<br />
All of these can be installed with <code>yum install</code> or the Arca Noae Package Manager (ANPM).<br />
<br />
Once the dependencies are met, simply download and extract the FreeM source code, and follow these steps:<br />
<br />
* Open an OS/2 Window (in the Command Prompts folder in OS/2 System or Computer on the desktop)<br />
* Run the following commands:<br />
<pre><br />
[C:\] bash<br />
$ export EMXOMFLD_TYPE=WLINK<br />
$ export EMXOMFLD_LINKER=wl.exe<br />
$ ./autogen.sh # only needed if installing from the CVS repo<br />
$ ./configure<br />
$ make install<br />
$ fmadm configure<br />
</pre><br />
<br />
Once this is done, proceed to the next section.<br />
<br />
== Workarounds ==<br />
Under OS/2 and ArcaOS, FreeM binaries are installed under <code>C:\USR\LOCAL\BIN</code>, but the FreeM daemon and the FreeM interpreter cannot be launched from the same executable (the daemon will start, but interpreters will give an error resembling <code>Resource busy</code>).<br />
<br />
The <code>fmadm configure</code> (and <code>fmadm reconfigure</code>) commands will automatically copy <code>C:\USR\LOCAL\BIN\freem.exe</code> to <code>C:\USR\LOCAL\BIN\freemd.exe</code>.<br />
<br />
== Running ==<br />
# Open an OS/2 Window command prompt<br />
# Run <code>bash</code><br />
# Run <code>/usr/local/bin/freemd -dk</code> to start the FreeM daemon<br />
# Minimize the FreeM daemon process<br />
# Open a second OS/2 Window command prompt<br />
# Run the following commands:<br />
<pre><br />
[C:\] CD \USR\LOCAL\BIN<br />
[C:\USR\LOCAL\BIN] FREEM<br />
</pre><br />
<br />
== Platform Limitations ==<br />
* Only one interpreter instance can be launched at a time<br />
* <code>JOB</code> does not work<br />
* Terminal windows are fixed in size to 80x24<br />
* The FreeM daemon must be launched in the foreground, as <code>fork()</code> is unsupported here (<code>freemd.exe</code> will refuse to launch if you do not pass the <code>-k</code> or <code>--nofork</code> flags).<br />
* Network sockets functionality is unavailable<br />
* Building without <code>readline</code> causes direct mode to echo each line of code entered<br />
* No binary package is available: once we have an RPM package for Red Hat-derived distributions, an OS/2 RPM should be fairly straightforward<br />
<br />
Documentation for porting UNIX applications to OS/2 is scant, which makes many of these issues difficult to work around. However, we do want to iron out all of these shortcomings and promote this port to Tier 1 status.<br />
<br />
== Required Kernel Tuning ==<br />
Coming soon.<br />
<br />
[[Category: Tier 2 Ports]]<br />
[[Category: Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(OS/2)&diff=394Platform Notes (OS/2)2025-04-10T16:52:32Z<p>Smw: /* Building and Installing */</p>
<hr />
<div>{{DevBranchFeature}}<br />
<br />
== Port Status ==<br />
OS/2 is a [[Tier 2 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM cvs-current (23 Mar 2025)<br />
<br />
== Testing Details ==<br />
We build and test the OS/2 port on an ArcaOS 5.1 VM running in VirtualBox.<br />
<br />
== Building and Installing ==<br />
Currently, the OS/2 port is only tested on ArcaOS, and you will need to install several things in order to build and run:<br />
<br />
* autoconf<br />
* automake<br />
* gcc<br />
* readline-devel<br />
* bash<br />
* binutils-devel<br />
* coreutils<br />
* emxrt<br />
* gawk<br />
* gcc-wlink<br />
* gcc-wrt<br />
* grep<br />
* info<br />
* libc-devel<br />
* libtool<br />
* kbuild-make<br />
* sed<br />
* tar<br />
* gzip<br />
<br />
All of these can be installed with <code>yum install</code> or the Arca Noae Package Manager (ANPM).<br />
<br />
Once the dependencies are met, simply download and extract the FreeM source code, and follow these steps:<br />
<br />
* Open an OS/2 Window (in the Command Prompts folder in OS/2 System or Computer on the desktop)<br />
* Run the following commands:<br />
<pre><br />
[C:\] bash<br />
$ export EMXOMFLD_TYPE=WLINK<br />
$ export EMXOMFLD_LINKER=wl.exe<br />
$ ./autogen.sh # only needed if installing from the CVS repo<br />
$ ./configure<br />
$ make install<br />
$ fmadm configure<br />
</pre><br />
<br />
Once this is done, proceed to the next section.<br />
<br />
== Workarounds ==<br />
Under OS/2 and ArcaOS, FreeM binaries are installed under <code>C:\USR\LOCAL\BIN</code>, but the FreeM daemon and the FreeM interpreter cannot be launched from the same executable (the daemon will start, but interpreters will give an error resembling <code>Resource busy</code>).<br />
<br />
The <code>fmadm configure</code> (and <code>fmadm reconfigure</code>) commands will automatically copy <code>C:\USR\LOCAL\BIN\freem.exe</code> to <code>C:\USR\LOCAL\BIN\freemd.exe</code>.<br />
<br />
== Running ==<br />
# Open an OS/2 Window command prompt<br />
# Run <code>bash</code><br />
# Run <code>/usr/local/bin/freemd -dk</code> to start the FreeM daemon<br />
# Minimize the FreeM daemon process<br />
# Open a second OS/2 Window command prompt<br />
# Run the following commands:<br />
<pre><br />
[C:\] CD \USR\LOCAL\BIN<br />
[C:\USR\LOCAL\BIN] FREEM<br />
</pre><br />
<br />
== Platform Limitations ==<br />
* Only one interpreter instance can be launched at a time<br />
* <code>JOB</code> does not work<br />
* Terminal windows are fixed in size to 80x24<br />
* The FreeM daemon must be launched in the foreground, as <code>fork()</code> is unsupported here (<code>freemd.exe</code> will refuse to launch if you do not pass the <code>-k</code> or <code>--nofork</code> flags).<br />
* Network sockets functionality is unavailable<br />
* Building without <code>readline</code> causes direct mode to echo each line of code entered<br />
* No binary package is available: once we have an RPM package for Red Hat-derived distributions, an OS/2 RPM should be fairly straightforward<br />
<br />
Documentation for porting UNIX applications to OS/2 is scant, which makes many of these issues difficult to work around. However, we do want to iron out all of these shortcomings and promote this port to Tier 1 status.<br />
<br />
== Required Kernel Tuning ==<br />
Coming soon.<br />
<br />
[[Category: Tier 2 Ports]]<br />
[[Category: Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=393Contributor Guide2025-04-05T22:32:46Z<p>Smw: /* C Standard */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions should be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions should not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
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.<br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is currently a shorthand for <code>autoreconf --install</code>. <br />
<br />
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.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
* You've modified <code>libfreem</code> and want to test it from a standard system location<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=392Contributor Guide2025-04-05T22:31:43Z<p>Smw: /* C Standard */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions should be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions should not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
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 ever compiler.<br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is currently a shorthand for <code>autoreconf --install</code>. <br />
<br />
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.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
* You've modified <code>libfreem</code> and want to test it from a standard system location<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Main_Page&diff=391Main Page2025-04-05T22:21:16Z<p>Smw: </p>
<hr />
<div>This wiki contains documentation not included in the [https://freem.coherent-logic.com/docs FreeM Manual], including platform-specific installation and configuration notes, project policies, technical deep-dives, and release notes.<br />
<br />
== Release Notes ==<br />
* [[Conformance Clause]]<br />
* [[FreeM 0.62.3]]<br />
* [[FreeM 0.62.2]]<br />
* [[FreeM 0.62.1]]<br />
* [[FreeM Lite]]<br />
* [[FreeM 0.59.2]]<br />
<br />
== Project Policies and Procedures ==<br />
* [[General Policies]]<br />
* [[Code of Conduct]]<br />
<br />
== Hacking FreeM Code ==<br />
* [[Contributor Guide]]<br />
* [[Release Procedure]]<br />
<br />
== Port Tiers ==<br />
* [[Port Tiers]]<br />
* [[:Category:Tier 1 Ports|Tier 1 Ports]]<br />
* [[:Category:Tier 2 Ports|Tier 2 Ports]]<br />
* [[:Category:Tier 3 Ports|Tier 3 Ports]]<br />
<br />
== Platform Notes ==<br />
=== Tier 1 Ports ===<br />
* [[Platform Notes (Solaris/Illumos)]]<br />
* [[Platform Notes (NetBSD)]]<br />
* [[Platform Notes (FreeBSD)]]<br />
* [[Platform Notes (GNU/Linux)]]<br />
* [[Platform Notes (OpenBSD)]]<br />
<br />
=== Tier 2 Ports ===<br />
* [[Platform Notes (OS/2)]]<br />
* [[Platform Notes (SCO OpenServer)]]<br />
* [[Platform Notes (Compaq Tru64 UNIX)]]<br />
* [[Platform Notes (IBM AIX)]]<br />
<br />
=== Tier 3 Ports ===<br />
* [[Platform Notes (GNU HURD)]]<br />
* [[Platform Notes (SGI IRIX)]]<br />
* [[Platform Notes (HP-UX)]]<br />
* [[Platform Notes (Mac OS X)]]<br />
* [[Platform Notes (Minix 3+)]]<br />
<br />
== Tips and Tricks ==<br />
* [[Subscript Rules (Local and Global)]]<br />
* [[Object-Oriented Programming in FreeM]]<br />
<br />
== Technical Deep-Dives ==<br />
* [[FreeM System Architecture]]<br />
* [[Event Handling in FreeM]]<br />
* [[FreeM Transaction Processing Architecture]]<br />
* [[What is the GUMP?]]<br />
* [[Namespace Rules]]<br />
* [[Routine and Global Search Path Internals]]<br />
<br />
== History ==<br />
* [[FreeM History]]<br />
* [[Original README from Shalom ha-Ashkenaz]]<br />
<br />
== Status of Popular M Applications in FreeM ==<br />
<br />
* [[Applications: VA VistA]]<br />
* [[Applications: VA FileMan]]<br />
* [[Applications: VPE (Victory Programming Environment)]]<br />
* [[Applications: M Web Server]]<br />
* [[Applications: GDS/JDS]]<br />
* [[Applications: MVTS (M Validation and Test Suite)]]<br />
<br />
== General M Topics ==<br />
* [[M User's Group]]<br />
* [[M Technology Association]]<br />
* [[M Development Committee]]<br />
* [[Cache and M Technology Association UK]]<br />
* [[M User's Group-Deutschland]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=390Contributor Guide2025-04-05T22:17:07Z<p>Smw: /* When to run make install */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is currently a shorthand for <code>autoreconf --install</code>. <br />
<br />
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.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
* You've modified <code>libfreem</code> and want to test it from a standard system location<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=389Contributor Guide2025-04-05T22:16:28Z<p>Smw: /* When to run autogen.sh */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is currently a shorthand for <code>autoreconf --install</code>. <br />
<br />
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.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=388Contributor Guide2025-04-05T22:16:12Z<p>Smw: /* When to run autogen.sh */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply 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.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=387Contributor Guide2025-04-05T22:13:02Z<p>Smw: /* Building FreeM */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
You can override the default installation location in the <code>configure</code> step with the following command:<br />
<br />
<pre><br />
$ ./configure --prefix=/path/to/desired/location<br />
</pre><br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=386Contributor Guide2025-04-05T22:11:52Z<p>Smw: /* Building FreeM */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
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.<br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=385Contributor Guide2025-04-05T22:10:14Z<p>Smw: /* Building FreeM */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[:Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=384Contributor Guide2025-04-05T22:09:49Z<p>Smw: /* Building FreeM */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[Category:Platform_Notes]] for any additional notes unique to your platform.<br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=383Contributor Guide2025-04-05T22:09:14Z<p>Smw: /* Building FreeM */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=382Contributor Guide2025-04-05T22:08:04Z<p>Smw: /* Building FreeM */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [Category:Platform Notes] for any additional notes unique to your platform.<br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=381Contributor Guide2025-04-05T22:07:46Z<p>Smw: </p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
Please see [[Category:Platform Notes]] for any additional notes unique to your platform.<br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=380Contributor Guide2025-04-05T22:04:05Z<p>Smw: /* Initial Build */</p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
==Initial Build==<br />
This applies to the first build after you've obtained the FreeM source code.<br />
<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>.<br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=379Contributor Guide2025-04-05T22:03:39Z<p>Smw: </p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre><br />
<br />
<br />
=Building FreeM=<br />
<br />
==Initial Build==<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>. <br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Contributor_Guide&diff=378Contributor Guide2025-04-05T22:01:56Z<p>Smw: </p>
<hr />
<div>=Overview=<br />
<br />
This article describes the facilities, methods, and commands used to contribute to the FreeM project.<br />
<br />
=For All Developers=<br />
<br />
==Overview==<br />
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 [https://freem.coherent-logic.com/docs/0.61.2/freem.html The FreeM Manual].<br />
<br />
You will also need to have <code>cvs</code> installed on your machine. This is available in the package repositories of all popular Linux and UNIX operating systems.<br />
<br />
==Language==<br />
All contributions to FreeM proper must be written in C. Bourne shell scripts are permissible where appropriate, and of course M code for the <code>mlib</code> routines.<br />
<br />
===C Standard===<br />
* FreeM contributions must not use language features unavailable in C89<br />
* Vendor extensions in C compilers (like GNU extensions) are only permitted if guarded by preprocessor macros, and should be avoided if possible<br />
* Contributions must be backwards compatible with gcc 2.95.3 (the oldest compiler we support)<br />
* Contributions must not break compiles on Sun <code>cc</code> or <code>clang</code><br />
<br />
===Autotools===<br />
* Contributions to <code>autoconf</code> and <code>automake</code> configuration must not use <code>pkg-config</code>, as it is unavailable on some of our target platforms<br />
* Target <code>autoconf</code> 2.54 and <code>automake</code> 1.7.1 for compatibility<br />
<br />
=Anonymous CVS Access=<br />
<br />
==Getting Source Code from CVS==<br />
To fetch the latest FreeM source code from CVS, run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot co freem<br />
</pre><br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
To update a previously-fetched copy of FreeM source code, go into the directory in which FreeM is located, and run the following command:<br />
<br />
<pre><br />
$ cvs -d:pserver:anonymous@cvs.coherent-logic.com:/home/cvsroot update -Pd<br />
</pre><br />
<br />
==Submitting Changes Without CVS Write Access==<br />
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:<br />
<br />
* What bug your patch fixes, or feature it implements<br />
* Your full preferred name (this will be used in order to credit you for your work)<br />
* Your preferred e-mail address<br />
<br />
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.<br />
<br />
=CVS Writer Access=<br />
<br />
==Requesting Writer Access==<br />
<br />
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 <br />
<code>freem-dev@mailman.chivanet.org</code>, including the following information:<br />
<br />
* Your full preferred name<br />
* Your preferred e-mail address<br />
* 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)<br />
<br />
==Configuring CVS==<br />
<br />
Once the below changes are made, you will need to log out and log back in to make them take effect.<br />
<br />
===Bourne-Again Shell (bash)===<br />
In <code>~/.bashrc</code> or <code>~/.bash_profile</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
export CVS_RSH=/usr/bin/ssh<br />
export CVSROOT=:ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
You may also need to change the <code>CVS_RSH</code> value to the correct absolute path to your <code>ssh</code> binary. You can find this information using <code>which ssh</code>.<br />
<br />
===C Shell===<br />
In <code>~/.cshrc</code>, add the following lines, substituting your <code>cvs.coherent-logic.com</code> username for ''username'':<br />
<br />
<pre><br />
setenv CVS_RSH /usr/bin/ssh<br />
setenv CVSROOT :ext:username@cvs.coherent-logic.com:/home/cvsroot<br />
</pre><br />
<br />
<br />
<br />
==Fetching FreeM Source Code==<br />
<br />
To fetch the latest FreeM source code for the first time, run the following command:<br />
<br />
<pre><br />
$ cvs co freem<br />
</pre><br />
<br />
If this fails, make sure you have the <code>CVS_RSH</code> and <code>CVSROOT</code> environment variables correctly configured.<br />
<br />
==Updating Your Copy of FreeM Source Code==<br />
<br />
In the directory containing the FreeM source code, run the following command:<br />
<br />
<pre><br />
$ cvs update -Pd<br />
</pre><br />
<br />
==Initial Build==<br />
Follow these steps for the initial build:<br />
<br />
# Change directories to the <code>freem</code> repository<br />
# Run <code>./autogen.sh</code><br />
# Run <code>./configure</code><br />
# Run <code>make</code><br />
# Run <code>sudo make install</code><br />
<br />
Once you have done the initial build, most changes shouldn't require more than a <code>make</code>. <br />
<br />
==Subsequent Builds==<br />
Most subsequent builds will just need a <code>make</code>. See the following paragraphs for caveats.<br />
<br />
===When to run autogen.sh===<br />
The <code>autogen.sh</code> script is simply a shorthand for <code>autoreconf --install</code>.<br />
<br />
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.<br />
<br />
===When to run make install===<br />
You should only need to run <code>make install</code> in the following scenarios:<br />
<br />
* You've changed the way the environment catalog (<code>env.conf</code>) or environment configuration files (<code>freem.conf</code>) work<br />
* You've modified a vendor routine in the <code>mlib/</code> directory<br />
<br />
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.<br />
<br />
<br />
<br />
==Adding Files to the Repository==<br />
<br />
Run the following commands from the <code>freem</code> directory, substituting the path and filename (relative to the <code>freem</code> directory) for <code>&lt;filename&gt;</code>:<br />
<br />
<pre><br />
$ cvs add <filename><br />
</pre><br />
<br />
==Committing Changes and Pushing to the Repository==<br />
<br />
Run the following commands ''from the parent directory of the <code>freem</code> directory'', replacing <code>commit-message</code> with a message describing the change:<br />
<br />
<pre><br />
$ cvs ci -m "commit-message"<br />
</pre></div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Database_Format&diff=377Database Format2025-04-05T17:25:33Z<p>Smw: </p>
<hr />
<div>From David Wicksell<br />
<pre><br />
The first block in my global is a bottom level pointer. Maybe that's what a ROOT block always is? But there is no data in any other block, as it's a brand new global. Confusing.<br />
Oh, I take that back. There is another block!<br />
So with a global with even just one small record in it, there will be more than one block.<br />
I suspect bottom pointer is called that because it's abstracted to be an upside down tree, and it's the root block for the global, which is the "bottom" of the global tree.<br />
I still don't quite understand this format though.<br />
That's block 0 of ^dlw. The 1, 3, and 1 on the top line appear to be pointers to another block, block 1.<br />
[4:33 PM]<br />
The end of that block has the metadata about the type of block it is, but the front of this block has at least one pointer to block number 1.<br />
Yep, that is definitive now. Block 1, or the second block, contains my first key, the only key, in the global, so far.<br />
[4:37 PM]<br />
I will figure this out.<br />
Ok, I see where key compression is done.<br />
[4:46 PM]<br />
I almost have the first block structure figured out.<br />
[4:51 PM]<br />
Ok, if the key you are going to insert isn't in the data block where it sorts to, then FreeM will lseek back in to the ROOT, and add the pointer first. So it has to traverse the path twice.<br />
Ok, that's strange. The key format for canonical numbers is odd. It turns a subscript of (2) in to a 5 in the key.<br />
[4:58 PM]<br />
I believe it also turns a (0) in to a 3 and a (1) in to a 4. I guess it can't use ASCII 0, 1, or 2 for that. (edited)<br />
[5:01 PM]<br />
I can definitelly see ways to speed up globals in FreeM! For one thing, it recalculates the file path to the global over and over, even when it has the file descriptor stored already.<br />
Ok, so I have the ROOT block, which is a bottom pointer block figured out, format wise.<br />
[5:21 PM]<br />
[5:24 PM]<br />
Starting at the first byte of the block, the 1 is the length of the first key in the global. Then it skips a byte, and the 3 is the first key. Then, because the block is a pointer block, all keys are hard-coded with a 3 byte pointer to their data block. So the next three bytes, 00 00 01 are a pointer to the block containing key 3. Now key 3 is actually ^dlw(1), but that 1 is encoded in to a compact key form, and ends up as 3. I'm not 100% sure why yet. So that points to block 1. I'm inserting a new pointer for ^dlw(2) right now, so in a few minutes, this first block will have another key up on the top line, and I'll show that to you once it's there.<br />
[5:25 PM]<br />
FreeM also maintains a path through the blocks in a global, just like RSM does and just like GT.M/YottaDB do.<br />
[5:28 PM]<br />
In RSM, that path is recorded in an array of pointers to global buffer descriptors in shared memory, called blk, it is 12 pointers long. In FreeM, the path seems to be in 2 arrays of longs, the first traceblk stores the block numbers in the path, and the second, traceadr also stores numbers, but shorts instead of unsigned longs. So far, I haven't figured out what it stores semantically. Both hold 32 numbers, so that would support the idea that it can handle a B-tree of 32 levels, which is gigantic<br />
dlw — Yesterday at 6:56 PM<br />
Ok, before inserting the second key, here is what block 0, the ROOT, a BOTTOM pointer for ^dlw looks like:<br />
"\001\000\003\000\000\001", '\000' <repeats 1010 times>, "\001\000\000\000\000\006\000\006"<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). Then, since it's a BOTTOM block, which is a pointer, and pointers are always 3 bytes, the next 3 bytes are 000 000 001, which when calculated is a pointer to block 1.<br />
<br />
Then, looking at the end of the block, the third to last byte is 006, which is the block type, BOTTOM. Then the last two bytes are 000 006, which, when calculated is an offset in to the block itself, of 6, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 006 type, is 3 bytes of 000 000 000, which would be the right pointer in a data block (maybe a pointer block too), but in the ROOT block, it's the number of free blocks in the global, which is 0, since there are only 2 blocks right now, and neither are empty. Then, one byte to the left of that is 000, which is the collation for the block, and a 0 is just M collation. Then, the three bytes before that are 000 000 001, and if this were a data block (maybe a pointer block too), it would be the left pointer, but since this is the ROOT block, it's the number of total blocks in the global, in this case 1. Since there is the ROOT block and a data block, the total block count must not include the ROOT block, but is how many more blocks.<br />
<br />
Next we'll look at the second block, a data block.<br />
dlw — Yesterday at 7:04 PM<br />
Ok, before inserting the second key, here is what block 1, the DATA block, for ^dlw looks like:<br />
"\001\000\003\0011", '\000' <repeats 1016 times>, "\b\000\005"<br />
<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). So far, identical to the ROOT, but once more keys are there, enough to need more blocks, then that will likely change. Then, since it's a DATA block, which is not a pointer, the next byte is the length of the data record at the key, which is a length of 1. Then, the next byte is 1 (ASCII 49, since the compact form is only in keys, and this is data), the data at ^dlw(1).<br />
<br />
Then, looking at the end of the block, the third to last byte is \b (which is 008), which is the block type, DATA. Then the lsat two bytes are 000 005, which, when calculated is an offset in to the block itself, of 5, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 008 type, is 3 bytes of 000 000 000, which would be the number of free blocks in the ROOT, but since this is DATA, is the right pointer. There are no blocks to the right, so it's 0. The, one byte to the left of that is 000, which in a DATA block is a reserved byte, and always 0. You could do something with that in the future. Then, the three bytes before that are 000 000 000, which would be the number of total blocks in the ROOT, but since this is DATA, is the left pointer. There are not blocks to the left, so it's 0.<br />
[7:06 PM]<br />
So that's what I've worked out so far. One observation, currently a key length is stored in two bytes, a byte for the length, and one for how much is compressed. So a key in a global in FreeM is restricted to 255 bytes without changing the format. The more important observatoin is that the length of a data record, or node, is stored in a single byte, also limiting it to 255 bytes without changing the format. Since I know you want to raise your string limits, you'll have to look at that first. I can help you figure out where to go and what to do if you like.<br />
<br />
dlw — Yesterday at 7:11 PM<br />
By the way, I'm doing this for two reasons. First, I love this sort of code, so I'm enjoying it. Second, and more importantly, I know you hate it, so I'm trying to help you out, because I want you to succeed at increasing the string length in FreeM.<br />
<br />
dlw — Yesterday at 7:55 PM<br />
Ok, I understand the FreeM block structure much better now.<br />
Ok, some weird things happen, they may or may not matter. I'll have to look in to that. But no block joins happen at all. Rather, most of a block that has all of its keys removed stays there empty.<br />
[12:37 AM]<br />
I had a global with 1 pointer block and 3 data blocks, and I killed all the records in the first and third data block, and for the most part, they are just sitting there all empty, while the second block is still full. The weirdness is that they both have one record still in them, and I'm not sure why. It's the last key, and it appears to have been moved to the front of the block. So maybe a FOR loop in FreeM is not inclusive in its END condtion, but exclusive. Or maybe something else is going on. Now I'm going to remove keys from the middle of the second block to see what happens.<br />
[12:41 AM]<br />
Blocks in FreeM do not contain their block number.<br />
[12:41 AM]<br />
I guess I just assumed they would.<br />
Ok, so that weirdness seems to just be an artifact, and I know why.<br />
<br />
dlw — 1:06 AM<br />
I was removing records in a loop, and when it got to the last record in a block, it didn't bother to remove it, instead it left it there, and just marked the block as empty. So it definitely does not do joins, it will remove records, and each time it does, it will re-key the block so that the keys after the one that was removed, are moved up to fill in the empty spot. Once it gets to that last record, it just marks the block free and leaves the record there, as the first record in the block.<br />
<br />
One thing I don't quite understand is that I created records to fill 3 data blocks, so there was 1 bottom pointer and 3 data blocks, but after all of that, what was left was block 0 was the bottom pointer, it has one pointer to block 2. Block 1 is marked empty and has one record in it, the original last record, as according to my last paragraph. Block 2 which I removed like 50 records from the middle of the block, and the records after it were moved up to fill the hole. Block 3 is marked empty and has one record in it at the beginning, the original last record, as according to my last paragraph. It also has a bunch of records at the end, but it's marked empty, so that seems fine. But why did leave them there, and why don't they match what I'd expect? They have records that were originally in block 3, and some of them are still there in block 3. So that part is a mystery, based on the code I ran, and the state of the blocks at each point. Block 5 is really weird. It was never used for data. But it has a few bits of things in it, and is marked as something I have no clue about, an FBLK. So not an EMPTY, but an FBLK. It is used though, as it has an offset and something before that offset and has that FBLK marker. So I'll have to figure out what an FBLK is and what it's used for. It's the one block type I don't know yet.<br />
[1:07 AM]<br />
Long story short, FreeM will always fill in holes during record deletion, by moving later records up to fill them, and it does not do block joins, it will just mark the block as empty. Both are things RSM does not do.<br />
[1:10 AM]<br />
Ohhhh!<br />
[1:10 AM]<br />
I know what it is!<br />
[1:10 AM]<br />
Clever!<br />
[1:12 AM]<br />
It's the free block list! So once FreeM has freed a block that had data in it, it creates a new block called the free block (FBLK), which is just a list of pointers to free blocks in order. So in my testing data, it just has a pointer to block 1 and block 3, which I told you above are both free. Does it always maintain that block at the end of the global somehow, or does it have another way of knowing where to find it? I'll have to figure that out.<br />
<br />
dlw — 1:15 AM<br />
Ooo, that's how!<br />
[1:17 AM]<br />
Remember earlier I told you that the ROOT block, always a BOTTOM pointer, didn't have a left and right pointer, since it has no siblings, so instead it uses those fields to store the number of blocks other than the ROOT that are in the global, and the number of free blocks? Yeah, it's not the number of free blocks, it's the block number that stores the FBLK, or free block list! So it can always find that block when it needs a new block, before it would add a new block to the global. So instead of a map block using a bitmap, like RSM uses, it has a pointer from the ROOT block to a FBLK, which maintains the list of free blocks!<br />
[1:18 AM]<br />
So there you go, other than a few details on internal key formats, I have taught you pretty much the entire globals module tonight! I have not dug in to block splits, but I'll do that soon, and let you know any details.<br />
[1:21 AM]<br />
So, remember that because all of the block pointers are 3 bytes, that means a global in FreeM can be at most, 16 MiB blocks, and at 1 KiB per block, that means no larger than 16 GiB.<br />
[1:22 AM]<br />
Just an FYI or a reminder.<br />
One other thing, FreeM's index/pointer block keys are different than RSM or GT.M/YottaDB.<br />
<br />
In GT.M/YottaDB, an index/pointer block stores keys such that the first key, which points to the first data block for that global, is a key that points to every key from the root of the global all the way to, and including, that key. In other words, the keys in the index blocks are the last keys stored in the data block they point to. Then at the end, there is a star pointer (a literal *, for everything else) that points to the last data block, containing any keys that collate after the previous key.<br />
<br />
In RSM, an index/pointer block stores keys such that the first key (always the null/empty/root key), which points to the first data block for that global, is a key that points to every key from the root of the global all the way to, and excluding the next key in the index block. In other words, the keys in the index blocks are the first keys stored in the data block they point to, and for the first key, even if there is no data at the root of the global, that key is still stored, just with no data if it doesn't exist (and it flagged as such in the entry for the global in the global directory). So the last key points at the first key in the last block that contains the keys to the end.<br />
<br />
In FreeM, an index/pointer block stores keys such that the first key, which points to the first data block for that global, is a key that points to every key, starting with that key, up to, and excluding, the next key in the index block. In other words, the keys in the index blocks are the first keys stored in the data block they point to. But unlike RSM, there is no key for before the first stored key (the null/empty/root key), the first key stored is the first key in the global. Also, unlike GT.M, there is no star pointer at the end. So every index pointer has to be updated if that key is deleted, with another one.<br />
t's basically a separately maintained linked-list that stores pointers to free blocks. I'm not sure if it would reorganize the pointers in order to keep them in block number order or not though.<br />
[11:14 AM]<br />
The root bottom pointer block stores the first free block in its footer, and then that block maintains a right pointer to the next free blook in the linked list, which itself has a left pointer back to the first, and so on. So it's a doubly-linked list.<br />
[11:16 AM]<br />
So if you wanted to calculate how many used blocks there are, you'd have to grab the block total from the ROOT footer, and then grab the block free pointer to the first free block, and walk through it, and its siblings, via the right pointers, marking down every block as free, and then what's left is used. There is no direct way to know what blocks are used, without walking the entire B-tree, other than the free block walk I just mentioned, which would be much faster.<br />
<br />
dlw — 11:21 AM<br />
The FBLK format is super simple. The footer maintains a left and right pointer, a block type of FBLK or 1, and an offset to the next available free space in the block. And then is just lists block numbers, 3 bytes at a time.<br />
[11:21 AM]<br />
No keys, or data, or anything else, just block pointers to free blocks, blocks with types of FREE or 0.<br />
[11:23 AM]<br />
The ROOT block's "right" pointer, points to the first FBLK for that global. The ROOT block's "left" pointer, stores the total number of blocks in the global, not including itself.<br />
[11:23 AM]<br />
But that does include FREE blocks and FBLK blocks.<br />
[11:25 AM]<br />
Because no spaces are allowed between keys, you can easily calculate how full a block is by simply subtracting the OFFSET (stored as the last two bytes in the footer) from DATALIM (the size of the block minus the footer, hard-coded), which then gives you how much free space is left in that block. True for all block types, other than FREE, which just have DATALIM of free space.<br />
[11:26 AM]<br />
Unlike RSM, which zeroes out blocks when they are garbage collected, FreeM leaves the data as-is when using or reusing a block, just setting the type to FREE, and the OFFSET to 0.<br />
[11:26 AM]<br />
Though when it goes to fill data in to a formerly FREE block, it will then zero the block I believe.<br />
</pre><br />
<br />
An older conversation about the key format:<br />
<pre><br />
The first byte is 1, that says that the key is 1 byte in length. The second byte is 0, that says there is no key compression. The third byte is 4B, which is 75 in decimal. That is the encoded character that encodes for this first key of length one. Here we use our decoding chops.<br />
[12:09 PM]<br />
75 is greater than 31, so we shift its bit pattern `0100 1011` to the right by 1, resulting in `0010 0101`, which is decimal 37. And since it was greater than 31, that's all you do to decode it (between 0 and 19 you do something else, and between 20 and 31, you do something else as well). And ASCII 37 is a % character, which is the full key for that node!<br />
<br />
dlw — 12/16/23, 12:10 PM<br />
The fourth byte is 0C, which is 12 decimal, which is the length of the data at that node, so 12 characters. Then the next 12 characters make up the data, and they don't encode subscript delimiters of course, so it's straight forward. Here that is:<br />
<br />
dlw — 12/16/23, 12:18 PM<br />
53 63 72 61 74 63 68 20 61 72 65 61 - which in decimal are - 83 99 114 97 116 99 104 32 97 114 101 97 - which are the ASCII codes for "Scratch area".<br />
[12:18 PM]<br />
So that key and its data are ^XVEMS("%")="Scratch area", which you can see is what FreeM things as well:<br />
USER> w ^XVEMS("%")<br />
Scratch area<br />
USER><br />
[12:19 PM]<br />
There was your first walk through of how to decode a FreeM key in a global! (edited)<br />
[12:20 PM]<br />
I'll do the next key, just to show you.<br />
[12:21 PM]<br />
<br />
[12:21 PM]<br />
This one has a longer key, and a shorter data node.<br />
<br />
dlw — 12/16/23, 12:28 PM<br />
So, the first byte is 9, so the key is 9 bytes. The second byte is 0, so no key compression here either. So then the next 9 bytes, the key, are:<br />
4B 12 02 04 12 11 A6 90 99 - which converted to the decimal we find easier to think about is - 75 18 2 4 18 17 166 144 153 - so now we have to decode them each in turn. First up is 75, which is higher than 31, so we take its bit pattern `0100 1011` and shift it to the right by one, leading to `0010 0101`, which is 37 decimal, or `%` again. That really should have been part of key compression, no idea what it wasn't. But,here we remember that these characters can encode that they are a subscript boundary, and they do that in their encoded form, which for `%` here, was 75. Remember the 75 bit pattern? It ended with a 1 in the LSB, which means this encodes as a delimiter too, so we now have `"%",` at this point.<br />
<br />
I'll continue on the next message.<br />
[12:31 PM]<br />
The second key byte is 18, with a bit pattern of 0001 0010 which does not end in 1, so this does not encode another , or the end of the key. Since this is between 0 and 19, we have to do an addition after the shift, but the shift is still one to the right, for 0000 1001, which is 9. Then, we add '0' to it, since this is numeric, and '0' is ASCII 48, so we get ASCII 57, which codes the number 9 as a string. So now our key is "%",9. On to the next byte, the third byte, which is 2. The bit pattern is 0000 0010 which doesn't end in 1, so doesn't end the subscript. It's a 2. That gets right shifted, to a 0000 0001, or a 1, which is then added to '0' (ASCII 48) to get ASCII 49, which is the code for a string of 1, which is not surprising, now that you see the patter. The key is at "%",91 now. (edited)<br />
<br />
dlw — 12/16/23, 12:41 PM<br />
Now we do the fourth byte, which is 4, same story, bit pattern is 0000 0100, not the end of a subscript, and it shifts to 0000 0010 a 2, which when added to '0' 48 again, becomes the string 2. Notice the pattern? When dealing with numerics or numbers, FreeM encodes them as what their ASCII code number is, and then just adds 48 to them, to get back their string equivalent. But since the get right shifted, and lose their last bit, they take up two places in the ASCII code.<br />
<br />
For example, ASCII 0 and 1 will result in a 0, 2 and 3 will result in a 1, 4 and 5 will result in a 2, and so on. So, you can take the ASCII number, if it's even, and cut it in half to get right to the number in a string form. And if it's odd, that means it is the last character for that subscript, and you can then subtract 1, and then cut it half to get the character, so an 18 is the number 9, while a 19 is the number 9, and it's the last character of the subsript!<br />
<br />
So to finish up the key, we are now at the fifth character, an 18, followed by a sixth, which is a 17. After that, the numbers are way over the 0 to 19 range for numbers. So an 18 is even and cut in half is 9, the next character decoded. The 17 is the first odd one, so it's the end of the subscript, take off 1, and cut in half, and you have 16 to 8, the last character. So our key now looks like "%",91298,.<br />
[12:41 PM]<br />
Now on to the last three characters, 166 144 153! (edited)<br />
[12:46 PM]<br />
So all are over 31, so only get right shifted. The first two are even, so they are part of a subscript, and the last one is odd, so it's the end of a subscript. But since the key was only 9 characters, FreeM won't put a , after them, but will end it with the ) instead.<br />
<br />
So 166 is 1010 0110, which right shifted is 0101 0011, which is a decimal 83, or the character S. 144 is 1001 0000 shifted right is 0100 1000a decimal 72, ASCII H. Then a 153, which is 1001 1001, shifted right is 0100 1100, a decimal 76, an ASCII L, so the last subscript is "SHL", and our key is finished!<br />
<br />
It is ("%",91298,"SHL").<br />
The next byte is a 3, so the data node is 3 characters, which are 52 55 4E, convert them to decimal and we have 82 85 78, which are the ASCII codes for R U N, and as data nodes aren't encoded with any shifting or masking or anything, that's just what they are! So the ("%",91298,"SHL") key stores "RUN". Now let's see if I was correct.<br />
[12:50 PM]<br />
USER> w $q(^XVEMS)<br />
^XVEMS("%")<br />
USER> w $q(^XVEMS("%"))<br />
^XVEMS("%",91298,"SHL")<br />
USER> w ^XVEMS("%")<br />
Scratch area<br />
USER> w ^XVEMS("%",91298,"SHL")<br />
RUN<br />
USER><br />
<br />
Yep! So that is how you decode global data in FreeM!<br />
Canonical numbers are shifted down in the control character range, so that they collate before strings, and that means control characters are unavailable for use. . and - are likewise moved to the area right after that, taking up a few other control characters. And strings are shifted up to over ASCII 127, taking over the higher bit, meaning only 7-bit ASCII is supported, no extended character sets.<br />
<br />
So the characters that it intends to allow in keys are ASCII 32 - 126, and that's it. Though it does something with 127, but I haven't figured it out yet.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:22 PM<br />
in light of everything you learned, have you gotten any new insights into how difficult it would be to get us to where we can support block sizes larger than 1KiB and a commensurate increase in key and node length? strictly in the globals themselves, not accounting for the interpreter having its own issues with long strings.<br />
<br />
dlw — 12/16/23, 1:25 PM<br />
There are only two things preventing a larger block size. First, BLOCKLEN is hard-coded, but you know that. Second, all the macros that offset off of BLOCKLEN are hard-coded, and would need to support scaling.<br />
<br />
If you fix those two things, you can have bigger block sizes. But, for longer keys and longer data, right now, each stores their lengths in a byte, limiting them to 255 characters. So you'd have to adjust the data size for key and/or record lengths to support larger ones.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:25 PM<br />
that's basically what I was thinking<br />
<br />
dlw — 12/16/23, 1:26 PM<br />
Sorry, they would not need to support scaling, they just need to follow the offset of a different BLOCKLEN. That's even easier than I was saying.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:26 PM<br />
haha that's what I thought you meant by scaling<br />
<br />
dlw — 12/16/23, 1:26 PM<br />
So if you set BLOCKLEN based on a user configuration, that should support block sizes larger than 1024 without much else.<br />
[1:26 PM]<br />
Scaling is multiplying, offsetting is adding.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:26 PM<br />
I've tried changing the BLOCKLEN macro to larger values, and FreeM did not behave well at all<br />
<br />
dlw — 12/16/23, 1:27 PM<br />
I'd have to follow all the places that use it to see why.<br />
[1:30 PM]<br />
BLOCKLEN is defined in 3 places. It should just work if you change it in all three to the same size.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:31 PM<br />
gfix.c, fma_globals.h, and mpsdef0.h?<br />
<br />
dlw — 12/16/23, 1:31 PM<br />
Yes<br />
[1:31 PM]<br />
But, you'd have to blow away every global you already have, and start with a brand new instance environment.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:31 PM<br />
yeah<br />
[1:32 PM]<br />
it wouldn't have much utility until nodes and/or keys can be longer than 255 characters<br />
<br />
dlw — 12/16/23, 1:32 PM<br />
Until you store the BLOCKLEN itself in block 0, which is totally possible, and probably easy.<br />
</pre><br />
<br />
<pre><br />
So in FreeM, when you insert a key between two existing keys in the same block, it will insert that key by moving the key after it, and every other key after it, down in the block, so that it keeps the block from having holes in between keys. But that can be expensive when it's inserting towards the front of a nearly full block. Though small blocks do help in that regard.<br />
<br />
In RSM, other than when it is doing things like block splits, block joins, or block reorganizations, it never moves keys, it stores them at the end of the block and keeps them tight, storing them in the order they are inserted, not in collation order like FreeM. Instead, it has a key index at the front of the block, right after the header, and the index uses fixed size offsets, and its that index that is kept in collation order. So when you insert a key between two existing keys in the same block, it will insert it in the next available space, pointed to by Last Free: above (scaled by 4), and then it will move the index for it, and every other key after it, down in the index. That also keeps the block from having holes in between keys, at least on inserts.<br />
<br />
On key removal, FreeM does the same exact thing as it does for inserts, but RSM will instead get a new block and copy all the keys to the new block, now in order not just in the index, but in the block key space itself, and skips removed keys.<br />
<br />
So to summarize, on insert, it just puts the key in the next available space and then rebuilds the block index in sorted order. On removal, it marks the key as undefined, and then grabs a new block, and copies everything to the new block except for the undefined key. (edited)<br />
</pre></div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Database_Format&diff=376Database Format2025-03-29T21:12:52Z<p>Smw: </p>
<hr />
<div>From David Wicksell<br />
<pre><br />
The first block in my global is a bottom level pointer. Maybe that's what a ROOT block always is? But there is no data in any other block, as it's a brand new global. Confusing.<br />
Oh, I take that back. There is another block!<br />
So with a global with even just one small record in it, there will be more than one block.<br />
I suspect bottom pointer is called that because it's abstracted to be an upside down tree, and it's the root block for the global, which is the "bottom" of the global tree.<br />
I still don't quite understand this format though.<br />
That's block 0 of ^dlw. The 1, 3, and 1 on the top line appear to be pointers to another block, block 1.<br />
[4:33 PM]<br />
The end of that block has the metadata about the type of block it is, but the front of this block has at least one pointer to block number 1.<br />
Yep, that is definitive now. Block 1, or the second block, contains my first key, the only key, in the global, so far.<br />
[4:37 PM]<br />
I will figure this out.<br />
Ok, I see where key compression is done.<br />
[4:46 PM]<br />
I almost have the first block structure figured out.<br />
[4:51 PM]<br />
Ok, if the key you are going to insert isn't in the data block where it sorts to, then FreeM will lseek back in to the ROOT, and add the pointer first. So it has to traverse the path twice.<br />
Ok, that's strange. The key format for canonical numbers is odd. It turns a subscript of (2) in to a 5 in the key.<br />
[4:58 PM]<br />
I believe it also turns a (0) in to a 3 and a (1) in to a 4. I guess it can't use ASCII 0, 1, or 2 for that. (edited)<br />
[5:01 PM]<br />
I can definitelly see ways to speed up globals in FreeM! For one thing, it recalculates the file path to the global over and over, even when it has the file descriptor stored already.<br />
Ok, so I have the ROOT block, which is a bottom pointer block figured out, format wise.<br />
[5:21 PM]<br />
[5:24 PM]<br />
Starting at the first byte of the block, the 1 is the length of the first key in the global. Then it skips a byte, and the 3 is the first key. Then, because the block is a pointer block, all keys are hard-coded with a 3 byte pointer to their data block. So the next three bytes, 00 00 01 are a pointer to the block containing key 3. Now key 3 is actually ^dlw(1), but that 1 is encoded in to a compact key form, and ends up as 3. I'm not 100% sure why yet. So that points to block 1. I'm inserting a new pointer for ^dlw(2) right now, so in a few minutes, this first block will have another key up on the top line, and I'll show that to you once it's there.<br />
[5:25 PM]<br />
FreeM also maintains a path through the blocks in a global, just like RSM does and just like GT.M/YottaDB do.<br />
[5:28 PM]<br />
In RSM, that path is recorded in an array of pointers to global buffer descriptors in shared memory, called blk, it is 12 pointers long. In FreeM, the path seems to be in 2 arrays of longs, the first traceblk stores the block numbers in the path, and the second, traceadr also stores numbers, but shorts instead of unsigned longs. So far, I haven't figured out what it stores semantically. Both hold 32 numbers, so that would support the idea that it can handle a B-tree of 32 levels, which is gigantic<br />
dlw — Yesterday at 6:56 PM<br />
Ok, before inserting the second key, here is what block 0, the ROOT, a BOTTOM pointer for ^dlw looks like:<br />
"\001\000\003\000\000\001", '\000' <repeats 1010 times>, "\001\000\000\000\000\006\000\006"<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). Then, since it's a BOTTOM block, which is a pointer, and pointers are always 3 bytes, the next 3 bytes are 000 000 001, which when calculated is a pointer to block 1.<br />
<br />
Then, looking at the end of the block, the third to last byte is 006, which is the block type, BOTTOM. Then the last two bytes are 000 006, which, when calculated is an offset in to the block itself, of 6, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 006 type, is 3 bytes of 000 000 000, which would be the right pointer in a data block (maybe a pointer block too), but in the ROOT block, it's the number of free blocks in the global, which is 0, since there are only 2 blocks right now, and neither are empty. Then, one byte to the left of that is 000, which is the collation for the block, and a 0 is just M collation. Then, the three bytes before that are 000 000 001, and if this were a data block (maybe a pointer block too), it would be the left pointer, but since this is the ROOT block, it's the number of total blocks in the global, in this case 1. Since there is the ROOT block and a data block, the total block count must not include the ROOT block, but is how many more blocks.<br />
<br />
Next we'll look at the second block, a data block.<br />
dlw — Yesterday at 7:04 PM<br />
Ok, before inserting the second key, here is what block 1, the DATA block, for ^dlw looks like:<br />
"\001\000\003\0011", '\000' <repeats 1016 times>, "\b\000\005"<br />
<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). So far, identical to the ROOT, but once more keys are there, enough to need more blocks, then that will likely change. Then, since it's a DATA block, which is not a pointer, the next byte is the length of the data record at the key, which is a length of 1. Then, the next byte is 1 (ASCII 49, since the compact form is only in keys, and this is data), the data at ^dlw(1).<br />
<br />
Then, looking at the end of the block, the third to last byte is \b (which is 008), which is the block type, DATA. Then the lsat two bytes are 000 005, which, when calculated is an offset in to the block itself, of 5, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 008 type, is 3 bytes of 000 000 000, which would be the number of free blocks in the ROOT, but since this is DATA, is the right pointer. There are no blocks to the right, so it's 0. The, one byte to the left of that is 000, which in a DATA block is a reserved byte, and always 0. You could do something with that in the future. Then, the three bytes before that are 000 000 000, which would be the number of total blocks in the ROOT, but since this is DATA, is the left pointer. There are not blocks to the left, so it's 0.<br />
[7:06 PM]<br />
So that's what I've worked out so far. One observation, currently a key length is stored in two bytes, a byte for the length, and one for how much is compressed. So a key in a global in FreeM is restricted to 255 bytes without changing the format. The more important observatoin is that the length of a data record, or node, is stored in a single byte, also limiting it to 255 bytes without changing the format. Since I know you want to raise your string limits, you'll have to look at that first. I can help you figure out where to go and what to do if you like.<br />
<br />
dlw — Yesterday at 7:11 PM<br />
By the way, I'm doing this for two reasons. First, I love this sort of code, so I'm enjoying it. Second, and more importantly, I know you hate it, so I'm trying to help you out, because I want you to succeed at increasing the string length in FreeM.<br />
<br />
dlw — Yesterday at 7:55 PM<br />
Ok, I understand the FreeM block structure much better now.<br />
Ok, some weird things happen, they may or may not matter. I'll have to look in to that. But no block joins happen at all. Rather, most of a block that has all of its keys removed stays there empty.<br />
[12:37 AM]<br />
I had a global with 1 pointer block and 3 data blocks, and I killed all the records in the first and third data block, and for the most part, they are just sitting there all empty, while the second block is still full. The weirdness is that they both have one record still in them, and I'm not sure why. It's the last key, and it appears to have been moved to the front of the block. So maybe a FOR loop in FreeM is not inclusive in its END condtion, but exclusive. Or maybe something else is going on. Now I'm going to remove keys from the middle of the second block to see what happens.<br />
[12:41 AM]<br />
Blocks in FreeM do not contain their block number.<br />
[12:41 AM]<br />
I guess I just assumed they would.<br />
Ok, so that weirdness seems to just be an artifact, and I know why.<br />
<br />
dlw — 1:06 AM<br />
I was removing records in a loop, and when it got to the last record in a block, it didn't bother to remove it, instead it left it there, and just marked the block as empty. So it definitely does not do joins, it will remove records, and each time it does, it will re-key the block so that the keys after the one that was removed, are moved up to fill in the empty spot. Once it gets to that last record, it just marks the block free and leaves the record there, as the first record in the block.<br />
<br />
One thing I don't quite understand is that I created records to fill 3 data blocks, so there was 1 bottom pointer and 3 data blocks, but after all of that, what was left was block 0 was the bottom pointer, it has one pointer to block 2. Block 1 is marked empty and has one record in it, the original last record, as according to my last paragraph. Block 2 which I removed like 50 records from the middle of the block, and the records after it were moved up to fill the hole. Block 3 is marked empty and has one record in it at the beginning, the original last record, as according to my last paragraph. It also has a bunch of records at the end, but it's marked empty, so that seems fine. But why did leave them there, and why don't they match what I'd expect? They have records that were originally in block 3, and some of them are still there in block 3. So that part is a mystery, based on the code I ran, and the state of the blocks at each point. Block 5 is really weird. It was never used for data. But it has a few bits of things in it, and is marked as something I have no clue about, an FBLK. So not an EMPTY, but an FBLK. It is used though, as it has an offset and something before that offset and has that FBLK marker. So I'll have to figure out what an FBLK is and what it's used for. It's the one block type I don't know yet.<br />
[1:07 AM]<br />
Long story short, FreeM will always fill in holes during record deletion, by moving later records up to fill them, and it does not do block joins, it will just mark the block as empty. Both are things RSM does not do.<br />
[1:10 AM]<br />
Ohhhh!<br />
[1:10 AM]<br />
I know what it is!<br />
[1:10 AM]<br />
Clever!<br />
[1:12 AM]<br />
It's the free block list! So once FreeM has freed a block that had data in it, it creates a new block called the free block (FBLK), which is just a list of pointers to free blocks in order. So in my testing data, it just has a pointer to block 1 and block 3, which I told you above are both free. Does it always maintain that block at the end of the global somehow, or does it have another way of knowing where to find it? I'll have to figure that out.<br />
<br />
dlw — 1:15 AM<br />
Ooo, that's how!<br />
[1:17 AM]<br />
Remember earlier I told you that the ROOT block, always a BOTTOM pointer, didn't have a left and right pointer, since it has no siblings, so instead it uses those fields to store the number of blocks other than the ROOT that are in the global, and the number of free blocks? Yeah, it's not the number of free blocks, it's the block number that stores the FBLK, or free block list! So it can always find that block when it needs a new block, before it would add a new block to the global. So instead of a map block using a bitmap, like RSM uses, it has a pointer from the ROOT block to a FBLK, which maintains the list of free blocks!<br />
[1:18 AM]<br />
So there you go, other than a few details on internal key formats, I have taught you pretty much the entire globals module tonight! I have not dug in to block splits, but I'll do that soon, and let you know any details.<br />
[1:21 AM]<br />
So, remember that because all of the block pointers are 3 bytes, that means a global in FreeM can be at most, 16 MiB blocks, and at 1 KiB per block, that means no larger than 16 GiB.<br />
[1:22 AM]<br />
Just an FYI or a reminder.<br />
One other thing, FreeM's index/pointer block keys are different than RSM or GT.M/YottaDB.<br />
<br />
In GT.M/YottaDB, an index/pointer block stores keys such that the first key, which points to the first data block for that global, is a key that points to every key from the root of the global all the way to, and including, that key. In other words, the keys in the index blocks are the last keys stored in the data block they point to. Then at the end, there is a star pointer (a literal *, for everything else) that points to the last data block, containing any keys that collate after the previous key.<br />
<br />
In RSM, an index/pointer block stores keys such that the first key (always the null/empty/root key), which points to the first data block for that global, is a key that points to every key from the root of the global all the way to, and excluding the next key in the index block. In other words, the keys in the index blocks are the first keys stored in the data block they point to, and for the first key, even if there is no data at the root of the global, that key is still stored, just with no data if it doesn't exist (and it flagged as such in the entry for the global in the global directory). So the last key points at the first key in the last block that contains the keys to the end.<br />
<br />
In FreeM, an index/pointer block stores keys such that the first key, which points to the first data block for that global, is a key that points to every key, starting with that key, up to, and excluding, the next key in the index block. In other words, the keys in the index blocks are the first keys stored in the data block they point to. But unlike RSM, there is no key for before the first stored key (the null/empty/root key), the first key stored is the first key in the global. Also, unlike GT.M, there is no star pointer at the end. So every index pointer has to be updated if that key is deleted, with another one.<br />
t's basically a separately maintained linked-list that stores pointers to free blocks. I'm not sure if it would reorganize the pointers in order to keep them in block number order or not though.<br />
[11:14 AM]<br />
The root bottom pointer block stores the first free block in its footer, and then that block maintains a right pointer to the next free blook in the linked list, which itself has a left pointer back to the first, and so on. So it's a doubly-linked list.<br />
[11:16 AM]<br />
So if you wanted to calculate how many used blocks there are, you'd have to grab the block total from the ROOT footer, and then grab the block free pointer to the first free block, and walk through it, and its siblings, via the right pointers, marking down every block as free, and then what's left is used. There is no direct way to know what blocks are used, without walking the entire B-tree, other than the free block walk I just mentioned, which would be much faster.<br />
<br />
dlw — 11:21 AM<br />
The FBLK format is super simple. The footer maintains a left and right pointer, a block type of FBLK or 1, and an offset to the next available free space in the block. And then is just lists block numbers, 3 bytes at a time.<br />
[11:21 AM]<br />
No keys, or data, or anything else, just block pointers to free blocks, blocks with types of FREE or 0.<br />
[11:23 AM]<br />
The ROOT block's "right" pointer, points to the first FBLK for that global. The ROOT block's "left" pointer, stores the total number of blocks in the global, not including itself.<br />
[11:23 AM]<br />
But that does include FREE blocks and FBLK blocks.<br />
[11:25 AM]<br />
Because no spaces are allowed between keys, you can easily calculate how full a block is by simply subtracting the OFFSET (stored as the last two bytes in the footer) from DATALIM (the size of the block minus the footer, hard-coded), which then gives you how much free space is left in that block. True for all block types, other than FREE, which just have DATALIM of free space.<br />
[11:26 AM]<br />
Unlike RSM, which zeroes out blocks when they are garbage collected, FreeM leaves the data as-is when using or reusing a block, just setting the type to FREE, and the OFFSET to 0.<br />
[11:26 AM]<br />
Though when it goes to fill data in to a formerly FREE block, it will then zero the block I believe.<br />
</pre><br />
<br />
An older conversation about the key format:<br />
<pre><br />
The first byte is 1, that says that the key is 1 byte in length. The second byte is 0, that says there is no key compression. The third byte is 4B, which is 75 in decimal. That is the encoded character that encodes for this first key of length one. Here we use our decoding chops.<br />
[12:09 PM]<br />
75 is greater than 31, so we shift its bit pattern `0100 1011` to the right by 1, resulting in `0010 0101`, which is decimal 37. And since it was greater than 31, that's all you do to decode it (between 0 and 19 you do something else, and between 20 and 31, you do something else as well). And ASCII 37 is a % character, which is the full key for that node!<br />
<br />
dlw — 12/16/23, 12:10 PM<br />
The fourth byte is 0C, which is 12 decimal, which is the length of the data at that node, so 12 characters. Then the next 12 characters make up the data, and they don't encode subscript delimiters of course, so it's straight forward. Here that is:<br />
<br />
dlw — 12/16/23, 12:18 PM<br />
53 63 72 61 74 63 68 20 61 72 65 61 - which in decimal are - 83 99 114 97 116 99 104 32 97 114 101 97 - which are the ASCII codes for "Scratch area".<br />
[12:18 PM]<br />
So that key and its data are ^XVEMS("%")="Scratch area", which you can see is what FreeM things as well:<br />
USER> w ^XVEMS("%")<br />
Scratch area<br />
USER><br />
[12:19 PM]<br />
There was your first walk through of how to decode a FreeM key in a global! (edited)<br />
[12:20 PM]<br />
I'll do the next key, just to show you.<br />
[12:21 PM]<br />
<br />
[12:21 PM]<br />
This one has a longer key, and a shorter data node.<br />
<br />
dlw — 12/16/23, 12:28 PM<br />
So, the first byte is 9, so the key is 9 bytes. The second byte is 0, so no key compression here either. So then the next 9 bytes, the key, are:<br />
4B 12 02 04 12 11 A6 90 99 - which converted to the decimal we find easier to think about is - 75 18 2 4 18 17 166 144 153 - so now we have to decode them each in turn. First up is 75, which is higher than 31, so we take its bit pattern `0100 1011` and shift it to the right by one, leading to `0010 0101`, which is 37 decimal, or `%` again. That really should have been part of key compression, no idea what it wasn't. But,here we remember that these characters can encode that they are a subscript boundary, and they do that in their encoded form, which for `%` here, was 75. Remember the 75 bit pattern? It ended with a 1 in the LSB, which means this encodes as a delimiter too, so we now have `"%",` at this point.<br />
<br />
I'll continue on the next message.<br />
[12:31 PM]<br />
The second key byte is 18, with a bit pattern of 0001 0010 which does not end in 1, so this does not encode another , or the end of the key. Since this is between 0 and 19, we have to do an addition after the shift, but the shift is still one to the right, for 0000 1001, which is 9. Then, we add '0' to it, since this is numeric, and '0' is ASCII 48, so we get ASCII 57, which codes the number 9 as a string. So now our key is "%",9. On to the next byte, the third byte, which is 2. The bit pattern is 0000 0010 which doesn't end in 1, so doesn't end the subscript. It's a 2. That gets right shifted, to a 0000 0001, or a 1, which is then added to '0' (ASCII 48) to get ASCII 49, which is the code for a string of 1, which is not surprising, now that you see the patter. The key is at "%",91 now. (edited)<br />
<br />
dlw — 12/16/23, 12:41 PM<br />
Now we do the fourth byte, which is 4, same story, bit pattern is 0000 0100, not the end of a subscript, and it shifts to 0000 0010 a 2, which when added to '0' 48 again, becomes the string 2. Notice the pattern? When dealing with numerics or numbers, FreeM encodes them as what their ASCII code number is, and then just adds 48 to them, to get back their string equivalent. But since the get right shifted, and lose their last bit, they take up two places in the ASCII code.<br />
<br />
For example, ASCII 0 and 1 will result in a 0, 2 and 3 will result in a 1, 4 and 5 will result in a 2, and so on. So, you can take the ASCII number, if it's even, and cut it in half to get right to the number in a string form. And if it's odd, that means it is the last character for that subscript, and you can then subtract 1, and then cut it half to get the character, so an 18 is the number 9, while a 19 is the number 9, and it's the last character of the subsript!<br />
<br />
So to finish up the key, we are now at the fifth character, an 18, followed by a sixth, which is a 17. After that, the numbers are way over the 0 to 19 range for numbers. So an 18 is even and cut in half is 9, the next character decoded. The 17 is the first odd one, so it's the end of the subscript, take off 1, and cut in half, and you have 16 to 8, the last character. So our key now looks like "%",91298,.<br />
[12:41 PM]<br />
Now on to the last three characters, 166 144 153! (edited)<br />
[12:46 PM]<br />
So all are over 31, so only get right shifted. The first two are even, so they are part of a subscript, and the last one is odd, so it's the end of a subscript. But since the key was only 9 characters, FreeM won't put a , after them, but will end it with the ) instead.<br />
<br />
So 166 is 1010 0110, which right shifted is 0101 0011, which is a decimal 83, or the character S. 144 is 1001 0000 shifted right is 0100 1000a decimal 72, ASCII H. Then a 153, which is 1001 1001, shifted right is 0100 1100, a decimal 76, an ASCII L, so the last subscript is "SHL", and our key is finished!<br />
<br />
It is ("%",91298,"SHL").<br />
The next byte is a 3, so the data node is 3 characters, which are 52 55 4E, convert them to decimal and we have 82 85 78, which are the ASCII codes for R U N, and as data nodes aren't encoded with any shifting or masking or anything, that's just what they are! So the ("%",91298,"SHL") key stores "RUN". Now let's see if I was correct.<br />
[12:50 PM]<br />
USER> w $q(^XVEMS)<br />
^XVEMS("%")<br />
USER> w $q(^XVEMS("%"))<br />
^XVEMS("%",91298,"SHL")<br />
USER> w ^XVEMS("%")<br />
Scratch area<br />
USER> w ^XVEMS("%",91298,"SHL")<br />
RUN<br />
USER><br />
<br />
Yep! So that is how you decode global data in FreeM!<br />
Canonical numbers are shifted down in the control character range, so that they collate before strings, and that means control characters are unavailable for use. . and - are likewise moved to the area right after that, taking up a few other control characters. And strings are shifted up to over ASCII 127, taking over the higher bit, meaning only 7-bit ASCII is supported, no extended character sets.<br />
<br />
So the characters that it intends to allow in keys are ASCII 32 - 126, and that's it. Though it does something with 127, but I haven't figured it out yet.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:22 PM<br />
in light of everything you learned, have you gotten any new insights into how difficult it would be to get us to where we can support block sizes larger than 1KiB and a commensurate increase in key and node length? strictly in the globals themselves, not accounting for the interpreter having its own issues with long strings.<br />
<br />
dlw — 12/16/23, 1:25 PM<br />
There are only two things preventing a larger block size. First, BLOCKLEN is hard-coded, but you know that. Second, all the macros that offset off of BLOCKLEN are hard-coded, and would need to support scaling.<br />
<br />
If you fix those two things, you can have bigger block sizes. But, for longer keys and longer data, right now, each stores their lengths in a byte, limiting them to 255 characters. So you'd have to adjust the data size for key and/or record lengths to support larger ones.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:25 PM<br />
that's basically what I was thinking<br />
<br />
dlw — 12/16/23, 1:26 PM<br />
Sorry, they would not need to support scaling, they just need to follow the offset of a different BLOCKLEN. That's even easier than I was saying.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:26 PM<br />
haha that's what I thought you meant by scaling<br />
<br />
dlw — 12/16/23, 1:26 PM<br />
So if you set BLOCKLEN based on a user configuration, that should support block sizes larger than 1024 without much else.<br />
[1:26 PM]<br />
Scaling is multiplying, offsetting is adding.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:26 PM<br />
I've tried changing the BLOCKLEN macro to larger values, and FreeM did not behave well at all<br />
<br />
dlw — 12/16/23, 1:27 PM<br />
I'd have to follow all the places that use it to see why.<br />
[1:30 PM]<br />
BLOCKLEN is defined in 3 places. It should just work if you change it in all three to the same size.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:31 PM<br />
gfix.c, fma_globals.h, and mpsdef0.h?<br />
<br />
dlw — 12/16/23, 1:31 PM<br />
Yes<br />
[1:31 PM]<br />
But, you'd have to blow away every global you already have, and start with a brand new instance environment.<br />
<br />
Serena Bloodfeather — 12/16/23, 1:31 PM<br />
yeah<br />
[1:32 PM]<br />
it wouldn't have much utility until nodes and/or keys can be longer than 255 characters<br />
<br />
dlw — 12/16/23, 1:32 PM<br />
Until you store the BLOCKLEN itself in block 0, which is totally possible, and probably easy.<br />
</pre></div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Database_Format&diff=375Database Format2025-03-29T18:42:43Z<p>Smw: </p>
<hr />
<div>From David Wicksell<br />
<pre><br />
The first block in my global is a bottom level pointer. Maybe that's what a ROOT block always is? But there is no data in any other block, as it's a brand new global. Confusing.<br />
Oh, I take that back. There is another block!<br />
So with a global with even just one small record in it, there will be more than one block.<br />
I suspect bottom pointer is called that because it's abstracted to be an upside down tree, and it's the root block for the global, which is the "bottom" of the global tree.<br />
I still don't quite understand this format though.<br />
That's block 0 of ^dlw. The 1, 3, and 1 on the top line appear to be pointers to another block, block 1.<br />
[4:33 PM]<br />
The end of that block has the metadata about the type of block it is, but the front of this block has at least one pointer to block number 1.<br />
Yep, that is definitive now. Block 1, or the second block, contains my first key, the only key, in the global, so far.<br />
[4:37 PM]<br />
I will figure this out.<br />
Ok, I see where key compression is done.<br />
[4:46 PM]<br />
I almost have the first block structure figured out.<br />
[4:51 PM]<br />
Ok, if the key you are going to insert isn't in the data block where it sorts to, then FreeM will lseek back in to the ROOT, and add the pointer first. So it has to traverse the path twice.<br />
Ok, that's strange. The key format for canonical numbers is odd. It turns a subscript of (2) in to a 5 in the key.<br />
[4:58 PM]<br />
I believe it also turns a (0) in to a 3 and a (1) in to a 4. I guess it can't use ASCII 0, 1, or 2 for that. (edited)<br />
[5:01 PM]<br />
I can definitelly see ways to speed up globals in FreeM! For one thing, it recalculates the file path to the global over and over, even when it has the file descriptor stored already.<br />
Ok, so I have the ROOT block, which is a bottom pointer block figured out, format wise.<br />
[5:21 PM]<br />
[5:24 PM]<br />
Starting at the first byte of the block, the 1 is the length of the first key in the global. Then it skips a byte, and the 3 is the first key. Then, because the block is a pointer block, all keys are hard-coded with a 3 byte pointer to their data block. So the next three bytes, 00 00 01 are a pointer to the block containing key 3. Now key 3 is actually ^dlw(1), but that 1 is encoded in to a compact key form, and ends up as 3. I'm not 100% sure why yet. So that points to block 1. I'm inserting a new pointer for ^dlw(2) right now, so in a few minutes, this first block will have another key up on the top line, and I'll show that to you once it's there.<br />
[5:25 PM]<br />
FreeM also maintains a path through the blocks in a global, just like RSM does and just like GT.M/YottaDB do.<br />
[5:28 PM]<br />
In RSM, that path is recorded in an array of pointers to global buffer descriptors in shared memory, called blk, it is 12 pointers long. In FreeM, the path seems to be in 2 arrays of longs, the first traceblk stores the block numbers in the path, and the second, traceadr also stores numbers, but shorts instead of unsigned longs. So far, I haven't figured out what it stores semantically. Both hold 32 numbers, so that would support the idea that it can handle a B-tree of 32 levels, which is gigantic<br />
dlw — Yesterday at 6:56 PM<br />
Ok, before inserting the second key, here is what block 0, the ROOT, a BOTTOM pointer for ^dlw looks like:<br />
"\001\000\003\000\000\001", '\000' <repeats 1010 times>, "\001\000\000\000\000\006\000\006"<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). Then, since it's a BOTTOM block, which is a pointer, and pointers are always 3 bytes, the next 3 bytes are 000 000 001, which when calculated is a pointer to block 1.<br />
<br />
Then, looking at the end of the block, the third to last byte is 006, which is the block type, BOTTOM. Then the last two bytes are 000 006, which, when calculated is an offset in to the block itself, of 6, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 006 type, is 3 bytes of 000 000 000, which would be the right pointer in a data block (maybe a pointer block too), but in the ROOT block, it's the number of free blocks in the global, which is 0, since there are only 2 blocks right now, and neither are empty. Then, one byte to the left of that is 000, which is the collation for the block, and a 0 is just M collation. Then, the three bytes before that are 000 000 001, and if this were a data block (maybe a pointer block too), it would be the left pointer, but since this is the ROOT block, it's the number of total blocks in the global, in this case 1. Since there is the ROOT block and a data block, the total block count must not include the ROOT block, but is how many more blocks.<br />
<br />
Next we'll look at the second block, a data block.<br />
dlw — Yesterday at 7:04 PM<br />
Ok, before inserting the second key, here is what block 1, the DATA block, for ^dlw looks like:<br />
"\001\000\003\0011", '\000' <repeats 1016 times>, "\b\000\005"<br />
<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). So far, identical to the ROOT, but once more keys are there, enough to need more blocks, then that will likely change. Then, since it's a DATA block, which is not a pointer, the next byte is the length of the data record at the key, which is a length of 1. Then, the next byte is 1 (ASCII 49, since the compact form is only in keys, and this is data), the data at ^dlw(1).<br />
<br />
Then, looking at the end of the block, the third to last byte is \b (which is 008), which is the block type, DATA. Then the lsat two bytes are 000 005, which, when calculated is an offset in to the block itself, of 5, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 008 type, is 3 bytes of 000 000 000, which would be the number of free blocks in the ROOT, but since this is DATA, is the right pointer. There are no blocks to the right, so it's 0. The, one byte to the left of that is 000, which in a DATA block is a reserved byte, and always 0. You could do something with that in the future. Then, the three bytes before that are 000 000 000, which would be the number of total blocks in the ROOT, but since this is DATA, is the left pointer. There are not blocks to the left, so it's 0.<br />
[7:06 PM]<br />
So that's what I've worked out so far. One observation, currently a key length is stored in two bytes, a byte for the length, and one for how much is compressed. So a key in a global in FreeM is restricted to 255 bytes without changing the format. The more important observatoin is that the length of a data record, or node, is stored in a single byte, also limiting it to 255 bytes without changing the format. Since I know you want to raise your string limits, you'll have to look at that first. I can help you figure out where to go and what to do if you like.<br />
<br />
dlw — Yesterday at 7:11 PM<br />
By the way, I'm doing this for two reasons. First, I love this sort of code, so I'm enjoying it. Second, and more importantly, I know you hate it, so I'm trying to help you out, because I want you to succeed at increasing the string length in FreeM.<br />
<br />
dlw — Yesterday at 7:55 PM<br />
Ok, I understand the FreeM block structure much better now.<br />
Ok, some weird things happen, they may or may not matter. I'll have to look in to that. But no block joins happen at all. Rather, most of a block that has all of its keys removed stays there empty.<br />
[12:37 AM]<br />
I had a global with 1 pointer block and 3 data blocks, and I killed all the records in the first and third data block, and for the most part, they are just sitting there all empty, while the second block is still full. The weirdness is that they both have one record still in them, and I'm not sure why. It's the last key, and it appears to have been moved to the front of the block. So maybe a FOR loop in FreeM is not inclusive in its END condtion, but exclusive. Or maybe something else is going on. Now I'm going to remove keys from the middle of the second block to see what happens.<br />
[12:41 AM]<br />
Blocks in FreeM do not contain their block number.<br />
[12:41 AM]<br />
I guess I just assumed they would.<br />
Ok, so that weirdness seems to just be an artifact, and I know why.<br />
<br />
dlw — 1:06 AM<br />
I was removing records in a loop, and when it got to the last record in a block, it didn't bother to remove it, instead it left it there, and just marked the block as empty. So it definitely does not do joins, it will remove records, and each time it does, it will re-key the block so that the keys after the one that was removed, are moved up to fill in the empty spot. Once it gets to that last record, it just marks the block free and leaves the record there, as the first record in the block.<br />
<br />
One thing I don't quite understand is that I created records to fill 3 data blocks, so there was 1 bottom pointer and 3 data blocks, but after all of that, what was left was block 0 was the bottom pointer, it has one pointer to block 2. Block 1 is marked empty and has one record in it, the original last record, as according to my last paragraph. Block 2 which I removed like 50 records from the middle of the block, and the records after it were moved up to fill the hole. Block 3 is marked empty and has one record in it at the beginning, the original last record, as according to my last paragraph. It also has a bunch of records at the end, but it's marked empty, so that seems fine. But why did leave them there, and why don't they match what I'd expect? They have records that were originally in block 3, and some of them are still there in block 3. So that part is a mystery, based on the code I ran, and the state of the blocks at each point. Block 5 is really weird. It was never used for data. But it has a few bits of things in it, and is marked as something I have no clue about, an FBLK. So not an EMPTY, but an FBLK. It is used though, as it has an offset and something before that offset and has that FBLK marker. So I'll have to figure out what an FBLK is and what it's used for. It's the one block type I don't know yet.<br />
[1:07 AM]<br />
Long story short, FreeM will always fill in holes during record deletion, by moving later records up to fill them, and it does not do block joins, it will just mark the block as empty. Both are things RSM does not do.<br />
[1:10 AM]<br />
Ohhhh!<br />
[1:10 AM]<br />
I know what it is!<br />
[1:10 AM]<br />
Clever!<br />
[1:12 AM]<br />
It's the free block list! So once FreeM has freed a block that had data in it, it creates a new block called the free block (FBLK), which is just a list of pointers to free blocks in order. So in my testing data, it just has a pointer to block 1 and block 3, which I told you above are both free. Does it always maintain that block at the end of the global somehow, or does it have another way of knowing where to find it? I'll have to figure that out.<br />
<br />
dlw — 1:15 AM<br />
Ooo, that's how!<br />
[1:17 AM]<br />
Remember earlier I told you that the ROOT block, always a BOTTOM pointer, didn't have a left and right pointer, since it has no siblings, so instead it uses those fields to store the number of blocks other than the ROOT that are in the global, and the number of free blocks? Yeah, it's not the number of free blocks, it's the block number that stores the FBLK, or free block list! So it can always find that block when it needs a new block, before it would add a new block to the global. So instead of a map block using a bitmap, like RSM uses, it has a pointer from the ROOT block to a FBLK, which maintains the list of free blocks!<br />
[1:18 AM]<br />
So there you go, other than a few details on internal key formats, I have taught you pretty much the entire globals module tonight! I have not dug in to block splits, but I'll do that soon, and let you know any details.<br />
[1:21 AM]<br />
So, remember that because all of the block pointers are 3 bytes, that means a global in FreeM can be at most, 16 MiB blocks, and at 1 KiB per block, that means no larger than 16 GiB.<br />
[1:22 AM]<br />
Just an FYI or a reminder.<br />
One other thing, FreeM's index/pointer block keys are different than RSM or GT.M/YottaDB.<br />
<br />
In GT.M/YottaDB, an index/pointer block stores keys such that the first key, which points to the first data block for that global, is a key that points to every key from the root of the global all the way to, and including, that key. In other words, the keys in the index blocks are the last keys stored in the data block they point to. Then at the end, there is a star pointer (a literal *, for everything else) that points to the last data block, containing any keys that collate after the previous key.<br />
<br />
In RSM, an index/pointer block stores keys such that the first key (always the null/empty/root key), which points to the first data block for that global, is a key that points to every key from the root of the global all the way to, and excluding the next key in the index block. In other words, the keys in the index blocks are the first keys stored in the data block they point to, and for the first key, even if there is no data at the root of the global, that key is still stored, just with no data if it doesn't exist (and it flagged as such in the entry for the global in the global directory). So the last key points at the first key in the last block that contains the keys to the end.<br />
<br />
In FreeM, an index/pointer block stores keys such that the first key, which points to the first data block for that global, is a key that points to every key, starting with that key, up to, and excluding, the next key in the index block. In other words, the keys in the index blocks are the first keys stored in the data block they point to. But unlike RSM, there is no key for before the first stored key (the null/empty/root key), the first key stored is the first key in the global. Also, unlike GT.M, there is no star pointer at the end. So every index pointer has to be updated if that key is deleted, with another one.<br />
t's basically a separately maintained linked-list that stores pointers to free blocks. I'm not sure if it would reorganize the pointers in order to keep them in block number order or not though.<br />
[11:14 AM]<br />
The root bottom pointer block stores the first free block in its footer, and then that block maintains a right pointer to the next free blook in the linked list, which itself has a left pointer back to the first, and so on. So it's a doubly-linked list.<br />
[11:16 AM]<br />
So if you wanted to calculate how many used blocks there are, you'd have to grab the block total from the ROOT footer, and then grab the block free pointer to the first free block, and walk through it, and its siblings, via the right pointers, marking down every block as free, and then what's left is used. There is no direct way to know what blocks are used, without walking the entire B-tree, other than the free block walk I just mentioned, which would be much faster.<br />
<br />
dlw — 11:21 AM<br />
The FBLK format is super simple. The footer maintains a left and right pointer, a block type of FBLK or 1, and an offset to the next available free space in the block. And then is just lists block numbers, 3 bytes at a time.<br />
[11:21 AM]<br />
No keys, or data, or anything else, just block pointers to free blocks, blocks with types of FREE or 0.<br />
[11:23 AM]<br />
The ROOT block's "right" pointer, points to the first FBLK for that global. The ROOT block's "left" pointer, stores the total number of blocks in the global, not including itself.<br />
[11:23 AM]<br />
But that does include FREE blocks and FBLK blocks.<br />
[11:25 AM]<br />
Because no spaces are allowed between keys, you can easily calculate how full a block is by simply subtracting the OFFSET (stored as the last two bytes in the footer) from DATALIM (the size of the block minus the footer, hard-coded), which then gives you how much free space is left in that block. True for all block types, other than FREE, which just have DATALIM of free space.<br />
[11:26 AM]<br />
Unlike RSM, which zeroes out blocks when they are garbage collected, FreeM leaves the data as-is when using or reusing a block, just setting the type to FREE, and the OFFSET to 0.<br />
[11:26 AM]<br />
Though when it goes to fill data in to a formerly FREE block, it will then zero the block I believe.<br />
</pre></div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Database_Format&diff=374Database Format2025-03-29T16:48:23Z<p>Smw: </p>
<hr />
<div>From David Wicksell<br />
<pre><br />
The first block in my global is a bottom level pointer. Maybe that's what a ROOT block always is? But there is no data in any other block, as it's a brand new global. Confusing.<br />
Oh, I take that back. There is another block!<br />
So with a global with even just one small record in it, there will be more than one block.<br />
I suspect bottom pointer is called that because it's abstracted to be an upside down tree, and it's the root block for the global, which is the "bottom" of the global tree.<br />
I still don't quite understand this format though.<br />
That's block 0 of ^dlw. The 1, 3, and 1 on the top line appear to be pointers to another block, block 1.<br />
[4:33 PM]<br />
The end of that block has the metadata about the type of block it is, but the front of this block has at least one pointer to block number 1.<br />
Yep, that is definitive now. Block 1, or the second block, contains my first key, the only key, in the global, so far.<br />
[4:37 PM]<br />
I will figure this out.<br />
Ok, I see where key compression is done.<br />
[4:46 PM]<br />
I almost have the first block structure figured out.<br />
[4:51 PM]<br />
Ok, if the key you are going to insert isn't in the data block where it sorts to, then FreeM will lseek back in to the ROOT, and add the pointer first. So it has to traverse the path twice.<br />
Ok, that's strange. The key format for canonical numbers is odd. It turns a subscript of (2) in to a 5 in the key.<br />
[4:58 PM]<br />
I believe it also turns a (0) in to a 3 and a (1) in to a 4. I guess it can't use ASCII 0, 1, or 2 for that. (edited)<br />
[5:01 PM]<br />
I can definitelly see ways to speed up globals in FreeM! For one thing, it recalculates the file path to the global over and over, even when it has the file descriptor stored already.<br />
Ok, so I have the ROOT block, which is a bottom pointer block figured out, format wise.<br />
[5:21 PM]<br />
[5:24 PM]<br />
Starting at the first byte of the block, the 1 is the length of the first key in the global. Then it skips a byte, and the 3 is the first key. Then, because the block is a pointer block, all keys are hard-coded with a 3 byte pointer to their data block. So the next three bytes, 00 00 01 are a pointer to the block containing key 3. Now key 3 is actually ^dlw(1), but that 1 is encoded in to a compact key form, and ends up as 3. I'm not 100% sure why yet. So that points to block 1. I'm inserting a new pointer for ^dlw(2) right now, so in a few minutes, this first block will have another key up on the top line, and I'll show that to you once it's there.<br />
[5:25 PM]<br />
FreeM also maintains a path through the blocks in a global, just like RSM does and just like GT.M/YottaDB do.<br />
[5:28 PM]<br />
In RSM, that path is recorded in an array of pointers to global buffer descriptors in shared memory, called blk, it is 12 pointers long. In FreeM, the path seems to be in 2 arrays of longs, the first traceblk stores the block numbers in the path, and the second, traceadr also stores numbers, but shorts instead of unsigned longs. So far, I haven't figured out what it stores semantically. Both hold 32 numbers, so that would support the idea that it can handle a B-tree of 32 levels, which is gigantic<br />
dlw — Yesterday at 6:56 PM<br />
Ok, before inserting the second key, here is what block 0, the ROOT, a BOTTOM pointer for ^dlw looks like:<br />
"\001\000\003\000\000\001", '\000' <repeats 1010 times>, "\001\000\000\000\000\006\000\006"<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). Then, since it's a BOTTOM block, which is a pointer, and pointers are always 3 bytes, the next 3 bytes are 000 000 001, which when calculated is a pointer to block 1.<br />
<br />
Then, looking at the end of the block, the third to last byte is 006, which is the block type, BOTTOM. Then the last two bytes are 000 006, which, when calculated is an offset in to the block itself, of 6, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 006 type, is 3 bytes of 000 000 000, which would be the right pointer in a data block (maybe a pointer block too), but in the ROOT block, it's the number of free blocks in the global, which is 0, since there are only 2 blocks right now, and neither are empty. Then, one byte to the left of that is 000, which is the collation for the block, and a 0 is just M collation. Then, the three bytes before that are 000 000 001, and if this were a data block (maybe a pointer block too), it would be the left pointer, but since this is the ROOT block, it's the number of total blocks in the global, in this case 1. Since there is the ROOT block and a data block, the total block count must not include the ROOT block, but is how many more blocks.<br />
<br />
Next we'll look at the second block, a data block.<br />
dlw — Yesterday at 7:04 PM<br />
Ok, before inserting the second key, here is what block 1, the DATA block, for ^dlw looks like:<br />
"\001\000\003\0011", '\000' <repeats 1016 times>, "\b\000\005"<br />
<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). So far, identical to the ROOT, but once more keys are there, enough to need more blocks, then that will likely change. Then, since it's a DATA block, which is not a pointer, the next byte is the length of the data record at the key, which is a length of 1. Then, the next byte is 1 (ASCII 49, since the compact form is only in keys, and this is data), the data at ^dlw(1).<br />
<br />
Then, looking at the end of the block, the third to last byte is \b (which is 008), which is the block type, DATA. Then the lsat two bytes are 000 005, which, when calculated is an offset in to the block itself, of 5, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 008 type, is 3 bytes of 000 000 000, which would be the number of free blocks in the ROOT, but since this is DATA, is the right pointer. There are no blocks to the right, so it's 0. The, one byte to the left of that is 000, which in a DATA block is a reserved byte, and always 0. You could do something with that in the future. Then, the three bytes before that are 000 000 000, which would be the number of total blocks in the ROOT, but since this is DATA, is the left pointer. There are not blocks to the left, so it's 0.<br />
[7:06 PM]<br />
So that's what I've worked out so far. One observation, currently a key length is stored in two bytes, a byte for the length, and one for how much is compressed. So a key in a global in FreeM is restricted to 255 bytes without changing the format. The more important observatoin is that the length of a data record, or node, is stored in a single byte, also limiting it to 255 bytes without changing the format. Since I know you want to raise your string limits, you'll have to look at that first. I can help you figure out where to go and what to do if you like.<br />
<br />
dlw — Yesterday at 7:11 PM<br />
By the way, I'm doing this for two reasons. First, I love this sort of code, so I'm enjoying it. Second, and more importantly, I know you hate it, so I'm trying to help you out, because I want you to succeed at increasing the string length in FreeM.<br />
<br />
dlw — Yesterday at 7:55 PM<br />
Ok, I understand the FreeM block structure much better now.<br />
Ok, some weird things happen, they may or may not matter. I'll have to look in to that. But no block joins happen at all. Rather, most of a block that has all of its keys removed stays there empty.<br />
[12:37 AM]<br />
I had a global with 1 pointer block and 3 data blocks, and I killed all the records in the first and third data block, and for the most part, they are just sitting there all empty, while the second block is still full. The weirdness is that they both have one record still in them, and I'm not sure why. It's the last key, and it appears to have been moved to the front of the block. So maybe a FOR loop in FreeM is not inclusive in its END condtion, but exclusive. Or maybe something else is going on. Now I'm going to remove keys from the middle of the second block to see what happens.<br />
[12:41 AM]<br />
Blocks in FreeM do not contain their block number.<br />
[12:41 AM]<br />
I guess I just assumed they would.<br />
Ok, so that weirdness seems to just be an artifact, and I know why.<br />
<br />
dlw — 1:06 AM<br />
I was removing records in a loop, and when it got to the last record in a block, it didn't bother to remove it, instead it left it there, and just marked the block as empty. So it definitely does not do joins, it will remove records, and each time it does, it will re-key the block so that the keys after the one that was removed, are moved up to fill in the empty spot. Once it gets to that last record, it just marks the block free and leaves the record there, as the first record in the block.<br />
<br />
One thing I don't quite understand is that I created records to fill 3 data blocks, so there was 1 bottom pointer and 3 data blocks, but after all of that, what was left was block 0 was the bottom pointer, it has one pointer to block 2. Block 1 is marked empty and has one record in it, the original last record, as according to my last paragraph. Block 2 which I removed like 50 records from the middle of the block, and the records after it were moved up to fill the hole. Block 3 is marked empty and has one record in it at the beginning, the original last record, as according to my last paragraph. It also has a bunch of records at the end, but it's marked empty, so that seems fine. But why did leave them there, and why don't they match what I'd expect? They have records that were originally in block 3, and some of them are still there in block 3. So that part is a mystery, based on the code I ran, and the state of the blocks at each point. Block 5 is really weird. It was never used for data. But it has a few bits of things in it, and is marked as something I have no clue about, an FBLK. So not an EMPTY, but an FBLK. It is used though, as it has an offset and something before that offset and has that FBLK marker. So I'll have to figure out what an FBLK is and what it's used for. It's the one block type I don't know yet.<br />
[1:07 AM]<br />
Long story short, FreeM will always fill in holes during record deletion, by moving later records up to fill them, and it does not do block joins, it will just mark the block as empty. Both are things RSM does not do.<br />
[1:10 AM]<br />
Ohhhh!<br />
[1:10 AM]<br />
I know what it is!<br />
[1:10 AM]<br />
Clever!<br />
[1:12 AM]<br />
It's the free block list! So once FreeM has freed a block that had data in it, it creates a new block called the free block (FBLK), which is just a list of pointers to free blocks in order. So in my testing data, it just has a pointer to block 1 and block 3, which I told you above are both free. Does it always maintain that block at the end of the global somehow, or does it have another way of knowing where to find it? I'll have to figure that out.<br />
<br />
dlw — 1:15 AM<br />
Ooo, that's how!<br />
[1:17 AM]<br />
Remember earlier I told you that the ROOT block, always a BOTTOM pointer, didn't have a left and right pointer, since it has no siblings, so instead it uses those fields to store the number of blocks other than the ROOT that are in the global, and the number of free blocks? Yeah, it's not the number of free blocks, it's the block number that stores the FBLK, or free block list! So it can always find that block when it needs a new block, before it would add a new block to the global. So instead of a map block using a bitmap, like RSM uses, it has a pointer from the ROOT block to a FBLK, which maintains the list of free blocks!<br />
[1:18 AM]<br />
So there you go, other than a few details on internal key formats, I have taught you pretty much the entire globals module tonight! I have not dug in to block splits, but I'll do that soon, and let you know any details.<br />
[1:21 AM]<br />
So, remember that because all of the block pointers are 3 bytes, that means a global in FreeM can be at most, 16 MiB blocks, and at 1 KiB per block, that means no larger than 16 GiB.<br />
[1:22 AM]<br />
Just an FYI or a reminder.<br />
One other thing, FreeM's index/pointer block keys are different than RSM or GT.M/YottaDB.<br />
<br />
In GT.M/YottaDB, an index/pointer block stores keys such that the first key, which points to the first data block for that global, is a key that points to every key from the root of the global all the way to, and including, that key. In other words, the keys in the index blocks are the last keys stored in the data block they point to. Then at the end, there is a star pointer (a literal *, for everything else) that points to the last data block, containing any keys that collate after the previous key.<br />
<br />
In RSM, an index/pointer block stores keys such that the first key (always the null/empty/root key), which points to the first data block for that global, is a key that points to every key from the root of the global all the way to, and excluding the next key in the index block. In other words, the keys in the index blocks are the first keys stored in the data block they point to, and for the first key, even if there is no data at the root of the global, that key is still stored, just with no data if it doesn't exist (and it flagged as such in the entry for the global in the global directory). So the last key points at the first key in the last block that contains the keys to the end.<br />
<br />
In FreeM, an index/pointer block stores keys such that the first key, which points to the first data block for that global, is a key that points to every key, starting with that key, up to, and excluding, the next key in the index block. In other words, the keys in the index blocks are the first keys stored in the data block they point to. But unlike RSM, there is no key for before the first stored key (the null/empty/root key), the first key stored is the first key in the global. Also, unlike GT.M, there is no star pointer at the end. So every index pointer has to be updated if that key is deleted, with another one.<br />
</pre></div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Database_Format&diff=373Database Format2025-03-29T16:40:13Z<p>Smw: </p>
<hr />
<div>From David Wicksell<br />
<pre><br />
The first block in my global is a bottom level pointer. Maybe that's what a ROOT block always is? But there is no data in any other block, as it's a brand new global. Confusing.<br />
Oh, I take that back. There is another block!<br />
So with a global with even just one small record in it, there will be more than one block.<br />
I suspect bottom pointer is called that because it's abstracted to be an upside down tree, and it's the root block for the global, which is the "bottom" of the global tree.<br />
I still don't quite understand this format though.<br />
That's block 0 of ^dlw. The 1, 3, and 1 on the top line appear to be pointers to another block, block 1.<br />
[4:33 PM]<br />
The end of that block has the metadata about the type of block it is, but the front of this block has at least one pointer to block number 1.<br />
Yep, that is definitive now. Block 1, or the second block, contains my first key, the only key, in the global, so far.<br />
[4:37 PM]<br />
I will figure this out.<br />
Ok, I see where key compression is done.<br />
[4:46 PM]<br />
I almost have the first block structure figured out.<br />
[4:51 PM]<br />
Ok, if the key you are going to insert isn't in the data block where it sorts to, then FreeM will lseek back in to the ROOT, and add the pointer first. So it has to traverse the path twice.<br />
Ok, that's strange. The key format for canonical numbers is odd. It turns a subscript of (2) in to a 5 in the key.<br />
[4:58 PM]<br />
I believe it also turns a (0) in to a 3 and a (1) in to a 4. I guess it can't use ASCII 0, 1, or 2 for that. (edited)<br />
[5:01 PM]<br />
I can definitelly see ways to speed up globals in FreeM! For one thing, it recalculates the file path to the global over and over, even when it has the file descriptor stored already.<br />
Ok, so I have the ROOT block, which is a bottom pointer block figured out, format wise.<br />
[5:21 PM]<br />
[5:24 PM]<br />
Starting at the first byte of the block, the 1 is the length of the first key in the global. Then it skips a byte, and the 3 is the first key. Then, because the block is a pointer block, all keys are hard-coded with a 3 byte pointer to their data block. So the next three bytes, 00 00 01 are a pointer to the block containing key 3. Now key 3 is actually ^dlw(1), but that 1 is encoded in to a compact key form, and ends up as 3. I'm not 100% sure why yet. So that points to block 1. I'm inserting a new pointer for ^dlw(2) right now, so in a few minutes, this first block will have another key up on the top line, and I'll show that to you once it's there.<br />
[5:25 PM]<br />
FreeM also maintains a path through the blocks in a global, just like RSM does and just like GT.M/YottaDB do.<br />
[5:28 PM]<br />
In RSM, that path is recorded in an array of pointers to global buffer descriptors in shared memory, called blk, it is 12 pointers long. In FreeM, the path seems to be in 2 arrays of longs, the first traceblk stores the block numbers in the path, and the second, traceadr also stores numbers, but shorts instead of unsigned longs. So far, I haven't figured out what it stores semantically. Both hold 32 numbers, so that would support the idea that it can handle a B-tree of 32 levels, which is gigantic<br />
dlw — Yesterday at 6:56 PM<br />
Ok, before inserting the second key, here is what block 0, the ROOT, a BOTTOM pointer for ^dlw looks like:<br />
"\001\000\003\000\000\001", '\000' <repeats 1010 times>, "\001\000\000\000\000\006\000\006"<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). Then, since it's a BOTTOM block, which is a pointer, and pointers are always 3 bytes, the next 3 bytes are 000 000 001, which when calculated is a pointer to block 1.<br />
<br />
Then, looking at the end of the block, the third to last byte is 006, which is the block type, BOTTOM. Then the last two bytes are 000 006, which, when calculated is an offset in to the block itself, of 6, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 006 type, is 3 bytes of 000 000 000, which would be the right pointer in a data block (maybe a pointer block too), but in the ROOT block, it's the number of free blocks in the global, which is 0, since there are only 2 blocks right now, and neither are empty. Then, one byte to the left of that is 000, which is the collation for the block, and a 0 is just M collation. Then, the three bytes before that are 000 000 001, and if this were a data block (maybe a pointer block too), it would be the left pointer, but since this is the ROOT block, it's the number of total blocks in the global, in this case 1. Since there is the ROOT block and a data block, the total block count must not include the ROOT block, but is how many more blocks.<br />
<br />
Next we'll look at the second block, a data block.<br />
dlw — Yesterday at 7:04 PM<br />
Ok, before inserting the second key, here is what block 1, the DATA block, for ^dlw looks like:<br />
"\001\000\003\0011", '\000' <repeats 1016 times>, "\b\000\005"<br />
<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). So far, identical to the ROOT, but once more keys are there, enough to need more blocks, then that will likely change. Then, since it's a DATA block, which is not a pointer, the next byte is the length of the data record at the key, which is a length of 1. Then, the next byte is 1 (ASCII 49, since the compact form is only in keys, and this is data), the data at ^dlw(1).<br />
<br />
Then, looking at the end of the block, the third to last byte is \b (which is 008), which is the block type, DATA. Then the lsat two bytes are 000 005, which, when calculated is an offset in to the block itself, of 5, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 008 type, is 3 bytes of 000 000 000, which would be the number of free blocks in the ROOT, but since this is DATA, is the right pointer. There are no blocks to the right, so it's 0. The, one byte to the left of that is 000, which in a DATA block is a reserved byte, and always 0. You could do something with that in the future. Then, the three bytes before that are 000 000 000, which would be the number of total blocks in the ROOT, but since this is DATA, is the left pointer. There are not blocks to the left, so it's 0.<br />
[7:06 PM]<br />
So that's what I've worked out so far. One observation, currently a key length is stored in two bytes, a byte for the length, and one for how much is compressed. So a key in a global in FreeM is restricted to 255 bytes without changing the format. The more important observatoin is that the length of a data record, or node, is stored in a single byte, also limiting it to 255 bytes without changing the format. Since I know you want to raise your string limits, you'll have to look at that first. I can help you figure out where to go and what to do if you like.<br />
<br />
dlw — Yesterday at 7:11 PM<br />
By the way, I'm doing this for two reasons. First, I love this sort of code, so I'm enjoying it. Second, and more importantly, I know you hate it, so I'm trying to help you out, because I want you to succeed at increasing the string length in FreeM.<br />
<br />
dlw — Yesterday at 7:55 PM<br />
Ok, I understand the FreeM block structure much better now.<br />
Ok, some weird things happen, they may or may not matter. I'll have to look in to that. But no block joins happen at all. Rather, most of a block that has all of its keys removed stays there empty.<br />
[12:37 AM]<br />
I had a global with 1 pointer block and 3 data blocks, and I killed all the records in the first and third data block, and for the most part, they are just sitting there all empty, while the second block is still full. The weirdness is that they both have one record still in them, and I'm not sure why. It's the last key, and it appears to have been moved to the front of the block. So maybe a FOR loop in FreeM is not inclusive in its END condtion, but exclusive. Or maybe something else is going on. Now I'm going to remove keys from the middle of the second block to see what happens.<br />
[12:41 AM]<br />
Blocks in FreeM do not contain their block number.<br />
[12:41 AM]<br />
I guess I just assumed they would.<br />
Ok, so that weirdness seems to just be an artifact, and I know why.<br />
<br />
dlw — 1:06 AM<br />
I was removing records in a loop, and when it got to the last record in a block, it didn't bother to remove it, instead it left it there, and just marked the block as empty. So it definitely does not do joins, it will remove records, and each time it does, it will re-key the block so that the keys after the one that was removed, are moved up to fill in the empty spot. Once it gets to that last record, it just marks the block free and leaves the record there, as the first record in the block.<br />
<br />
One thing I don't quite understand is that I created records to fill 3 data blocks, so there was 1 bottom pointer and 3 data blocks, but after all of that, what was left was block 0 was the bottom pointer, it has one pointer to block 2. Block 1 is marked empty and has one record in it, the original last record, as according to my last paragraph. Block 2 which I removed like 50 records from the middle of the block, and the records after it were moved up to fill the hole. Block 3 is marked empty and has one record in it at the beginning, the original last record, as according to my last paragraph. It also has a bunch of records at the end, but it's marked empty, so that seems fine. But why did leave them there, and why don't they match what I'd expect? They have records that were originally in block 3, and some of them are still there in block 3. So that part is a mystery, based on the code I ran, and the state of the blocks at each point. Block 5 is really weird. It was never used for data. But it has a few bits of things in it, and is marked as something I have no clue about, an FBLK. So not an EMPTY, but an FBLK. It is used though, as it has an offset and something before that offset and has that FBLK marker. So I'll have to figure out what an FBLK is and what it's used for. It's the one block type I don't know yet.<br />
[1:07 AM]<br />
Long story short, FreeM will always fill in holes during record deletion, by moving later records up to fill them, and it does not do block joins, it will just mark the block as empty. Both are things RSM does not do.<br />
[1:10 AM]<br />
Ohhhh!<br />
[1:10 AM]<br />
I know what it is!<br />
[1:10 AM]<br />
Clever!<br />
[1:12 AM]<br />
It's the free block list! So once FreeM has freed a block that had data in it, it creates a new block called the free block (FBLK), which is just a list of pointers to free blocks in order. So in my testing data, it just has a pointer to block 1 and block 3, which I told you above are both free. Does it always maintain that block at the end of the global somehow, or does it have another way of knowing where to find it? I'll have to figure that out.<br />
<br />
dlw — 1:15 AM<br />
Ooo, that's how!<br />
[1:17 AM]<br />
Remember earlier I told you that the ROOT block, always a BOTTOM pointer, didn't have a left and right pointer, since it has no siblings, so instead it uses those fields to store the number of blocks other than the ROOT that are in the global, and the number of free blocks? Yeah, it's not the number of free blocks, it's the block number that stores the FBLK, or free block list! So it can always find that block when it needs a new block, before it would add a new block to the global. So instead of a map block using a bitmap, like RSM uses, it has a pointer from the ROOT block to a FBLK, which maintains the list of free blocks!<br />
[1:18 AM]<br />
So there you go, other than a few details on internal key formats, I have taught you pretty much the entire globals module tonight! I have not dug in to block splits, but I'll do that soon, and let you know any details.<br />
[1:21 AM]<br />
So, remember that because all of the block pointers are 3 bytes, that means a global in FreeM can be at most, 16 MiB blocks, and at 1 KiB per block, that means no larger than 16 GiB.<br />
[1:22 AM]<br />
Just an FYI or a reminder.<br />
</pre></div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Database_Format&diff=372Database Format2025-03-29T16:38:48Z<p>Smw: Created page with "<pre> The first block in my global is a bottom level pointer. Maybe that's what a ROOT block always is? But there is no data in any other block, as it's a brand new global. Co..."</p>
<hr />
<div><pre><br />
The first block in my global is a bottom level pointer. Maybe that's what a ROOT block always is? But there is no data in any other block, as it's a brand new global. Confusing.<br />
Oh, I take that back. There is another block!<br />
So with a global with even just one small record in it, there will be more than one block.<br />
I suspect bottom pointer is called that because it's abstracted to be an upside down tree, and it's the root block for the global, which is the "bottom" of the global tree.<br />
I still don't quite understand this format though.<br />
That's block 0 of ^dlw. The 1, 3, and 1 on the top line appear to be pointers to another block, block 1.<br />
[4:33 PM]<br />
The end of that block has the metadata about the type of block it is, but the front of this block has at least one pointer to block number 1.<br />
Yep, that is definitive now. Block 1, or the second block, contains my first key, the only key, in the global, so far.<br />
[4:37 PM]<br />
I will figure this out.<br />
Ok, I see where key compression is done.<br />
[4:46 PM]<br />
I almost have the first block structure figured out.<br />
[4:51 PM]<br />
Ok, if the key you are going to insert isn't in the data block where it sorts to, then FreeM will lseek back in to the ROOT, and add the pointer first. So it has to traverse the path twice.<br />
Ok, that's strange. The key format for canonical numbers is odd. It turns a subscript of (2) in to a 5 in the key.<br />
[4:58 PM]<br />
I believe it also turns a (0) in to a 3 and a (1) in to a 4. I guess it can't use ASCII 0, 1, or 2 for that. (edited)<br />
[5:01 PM]<br />
I can definitelly see ways to speed up globals in FreeM! For one thing, it recalculates the file path to the global over and over, even when it has the file descriptor stored already.<br />
Ok, so I have the ROOT block, which is a bottom pointer block figured out, format wise.<br />
[5:21 PM]<br />
[5:24 PM]<br />
Starting at the first byte of the block, the 1 is the length of the first key in the global. Then it skips a byte, and the 3 is the first key. Then, because the block is a pointer block, all keys are hard-coded with a 3 byte pointer to their data block. So the next three bytes, 00 00 01 are a pointer to the block containing key 3. Now key 3 is actually ^dlw(1), but that 1 is encoded in to a compact key form, and ends up as 3. I'm not 100% sure why yet. So that points to block 1. I'm inserting a new pointer for ^dlw(2) right now, so in a few minutes, this first block will have another key up on the top line, and I'll show that to you once it's there.<br />
[5:25 PM]<br />
FreeM also maintains a path through the blocks in a global, just like RSM does and just like GT.M/YottaDB do.<br />
[5:28 PM]<br />
In RSM, that path is recorded in an array of pointers to global buffer descriptors in shared memory, called blk, it is 12 pointers long. In FreeM, the path seems to be in 2 arrays of longs, the first traceblk stores the block numbers in the path, and the second, traceadr also stores numbers, but shorts instead of unsigned longs. So far, I haven't figured out what it stores semantically. Both hold 32 numbers, so that would support the idea that it can handle a B-tree of 32 levels, which is gigantic<br />
dlw — Yesterday at 6:56 PM<br />
Ok, before inserting the second key, here is what block 0, the ROOT, a BOTTOM pointer for ^dlw looks like:<br />
"\001\000\003\000\000\001", '\000' <repeats 1010 times>, "\001\000\000\000\000\006\000\006"<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). Then, since it's a BOTTOM block, which is a pointer, and pointers are always 3 bytes, the next 3 bytes are 000 000 001, which when calculated is a pointer to block 1.<br />
<br />
Then, looking at the end of the block, the third to last byte is 006, which is the block type, BOTTOM. Then the last two bytes are 000 006, which, when calculated is an offset in to the block itself, of 6, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 006 type, is 3 bytes of 000 000 000, which would be the right pointer in a data block (maybe a pointer block too), but in the ROOT block, it's the number of free blocks in the global, which is 0, since there are only 2 blocks right now, and neither are empty. Then, one byte to the left of that is 000, which is the collation for the block, and a 0 is just M collation. Then, the three bytes before that are 000 000 001, and if this were a data block (maybe a pointer block too), it would be the left pointer, but since this is the ROOT block, it's the number of total blocks in the global, in this case 1. Since there is the ROOT block and a data block, the total block count must not include the ROOT block, but is how many more blocks.<br />
<br />
Next we'll look at the second block, a data block.<br />
dlw — Yesterday at 7:04 PM<br />
Ok, before inserting the second key, here is what block 1, the DATA block, for ^dlw looks like:<br />
"\001\000\003\0011", '\000' <repeats 1016 times>, "\b\000\005"<br />
<br />
You can see stuff at the beginning and the end. Starting at the beginning, is 001 then 000, which added together is 1 (because of key compression), the length of the first key. Then the key is 003 (which is the compact form of (1) I guess). So far, identical to the ROOT, but once more keys are there, enough to need more blocks, then that will likely change. Then, since it's a DATA block, which is not a pointer, the next byte is the length of the data record at the key, which is a length of 1. Then, the next byte is 1 (ASCII 49, since the compact form is only in keys, and this is data), the data at ^dlw(1).<br />
<br />
Then, looking at the end of the block, the third to last byte is \b (which is 008), which is the block type, DATA. Then the lsat two bytes are 000 005, which, when calculated is an offset in to the block itself, of 5, meaning that it's the beginning of the free space in the block, offset from the beginning of the block. Then, to the left of the 008 type, is 3 bytes of 000 000 000, which would be the number of free blocks in the ROOT, but since this is DATA, is the right pointer. There are no blocks to the right, so it's 0. The, one byte to the left of that is 000, which in a DATA block is a reserved byte, and always 0. You could do something with that in the future. Then, the three bytes before that are 000 000 000, which would be the number of total blocks in the ROOT, but since this is DATA, is the left pointer. There are not blocks to the left, so it's 0.<br />
[7:06 PM]<br />
So that's what I've worked out so far. One observation, currently a key length is stored in two bytes, a byte for the length, and one for how much is compressed. So a key in a global in FreeM is restricted to 255 bytes without changing the format. The more important observatoin is that the length of a data record, or node, is stored in a single byte, also limiting it to 255 bytes without changing the format. Since I know you want to raise your string limits, you'll have to look at that first. I can help you figure out where to go and what to do if you like.<br />
<br />
dlw — Yesterday at 7:11 PM<br />
By the way, I'm doing this for two reasons. First, I love this sort of code, so I'm enjoying it. Second, and more importantly, I know you hate it, so I'm trying to help you out, because I want you to succeed at increasing the string length in FreeM.<br />
<br />
dlw — Yesterday at 7:55 PM<br />
Ok, I understand the FreeM block structure much better now.<br />
Ok, some weird things happen, they may or may not matter. I'll have to look in to that. But no block joins happen at all. Rather, most of a block that has all of its keys removed stays there empty.<br />
[12:37 AM]<br />
I had a global with 1 pointer block and 3 data blocks, and I killed all the records in the first and third data block, and for the most part, they are just sitting there all empty, while the second block is still full. The weirdness is that they both have one record still in them, and I'm not sure why. It's the last key, and it appears to have been moved to the front of the block. So maybe a FOR loop in FreeM is not inclusive in its END condtion, but exclusive. Or maybe something else is going on. Now I'm going to remove keys from the middle of the second block to see what happens.<br />
[12:41 AM]<br />
Blocks in FreeM do not contain their block number.<br />
[12:41 AM]<br />
I guess I just assumed they would.<br />
Ok, so that weirdness seems to just be an artifact, and I know why.<br />
<br />
dlw — 1:06 AM<br />
I was removing records in a loop, and when it got to the last record in a block, it didn't bother to remove it, instead it left it there, and just marked the block as empty. So it definitely does not do joins, it will remove records, and each time it does, it will re-key the block so that the keys after the one that was removed, are moved up to fill in the empty spot. Once it gets to that last record, it just marks the block free and leaves the record there, as the first record in the block.<br />
<br />
One thing I don't quite understand is that I created records to fill 3 data blocks, so there was 1 bottom pointer and 3 data blocks, but after all of that, what was left was block 0 was the bottom pointer, it has one pointer to block 2. Block 1 is marked empty and has one record in it, the original last record, as according to my last paragraph. Block 2 which I removed like 50 records from the middle of the block, and the records after it were moved up to fill the hole. Block 3 is marked empty and has one record in it at the beginning, the original last record, as according to my last paragraph. It also has a bunch of records at the end, but it's marked empty, so that seems fine. But why did leave them there, and why don't they match what I'd expect? They have records that were originally in block 3, and some of them are still there in block 3. So that part is a mystery, based on the code I ran, and the state of the blocks at each point. Block 5 is really weird. It was never used for data. But it has a few bits of things in it, and is marked as something I have no clue about, an FBLK. So not an EMPTY, but an FBLK. It is used though, as it has an offset and something before that offset and has that FBLK marker. So I'll have to figure out what an FBLK is and what it's used for. It's the one block type I don't know yet.<br />
[1:07 AM]<br />
Long story short, FreeM will always fill in holes during record deletion, by moving later records up to fill them, and it does not do block joins, it will just mark the block as empty. Both are things RSM does not do.<br />
[1:10 AM]<br />
Ohhhh!<br />
[1:10 AM]<br />
I know what it is!<br />
[1:10 AM]<br />
Clever!<br />
[1:12 AM]<br />
It's the free block list! So once FreeM has freed a block that had data in it, it creates a new block called the free block (FBLK), which is just a list of pointers to free blocks in order. So in my testing data, it just has a pointer to block 1 and block 3, which I told you above are both free. Does it always maintain that block at the end of the global somehow, or does it have another way of knowing where to find it? I'll have to figure that out.<br />
<br />
dlw — 1:15 AM<br />
Ooo, that's how!<br />
[1:17 AM]<br />
Remember earlier I told you that the ROOT block, always a BOTTOM pointer, didn't have a left and right pointer, since it has no siblings, so instead it uses those fields to store the number of blocks other than the ROOT that are in the global, and the number of free blocks? Yeah, it's not the number of free blocks, it's the block number that stores the FBLK, or free block list! So it can always find that block when it needs a new block, before it would add a new block to the global. So instead of a map block using a bitmap, like RSM uses, it has a pointer from the ROOT block to a FBLK, which maintains the list of free blocks!<br />
[1:18 AM]<br />
So there you go, other than a few details on internal key formats, I have taught you pretty much the entire globals module tonight! I have not dug in to block splits, but I'll do that soon, and let you know any details.<br />
[1:21 AM]<br />
So, remember that because all of the block pointers are 3 bytes, that means a global in FreeM can be at most, 16 MiB blocks, and at 1 KiB per block, that means no larger than 16 GiB.<br />
[1:22 AM]<br />
Just an FYI or a reminder.<br />
</pre></div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Release_Procedure&diff=371Release Procedure2025-03-28T13:01:26Z<p>Smw: </p>
<hr />
<div>{{InternalUseFeature}}<br />
=Overview=<br />
<br />
In all steps, replace ''version'' with the new version you want to release.<br />
<br />
==Prepare the FreeM Repository==<br />
<br />
===Set the Release Version===<br />
In the root of the <code>freem</code> repository, run <code>scripts/set-version ''version''</code><br />
<br />
===Update the ChangeLog===<br />
Make sure the <code>ChangeLog</code> file summarizes the changes present in this version<br />
<br />
===Commit and Tag===<br />
In the root of the <code>freem</code> repository, run these commands:<br />
<br />
<pre><br />
$ cvs ci -m "Commit message"<br />
</pre><br />
<br />
Now, wait for the build farm to crunch through the build on all platforms. If there are issues during this phase, fix them and commit to CVS before proceeding to the next step.<br />
<br />
===Verify Tier 1 Ports===<br />
Verify the correct operation of FreeM for the Tier 1 ports, and update their Platform Notes in the wiki:<br />
* Solaris (5.8/sparcv9, 5.7/sparc, 5.11/amd64, 5.11/sparcv9, 5.10/sparcv9)<br />
* OpenIndiana (5.11/amd64)<br />
* NetBSD<br />
* FreeBSD<br />
* GNU/Linux (one amd64 machine, one i386 machine, Raspberry Pi, and Pine Phone should be sufficient)<br />
<br />
Once the build is clean, go to the parent directory of the freem repository and run the following commands to tag the release:<br />
<br />
<pre><br />
$ cvs tag vMaj-Min-Patch freem<br />
</pre><br />
<br />
Now, wait for the <code>freem-current-source-tarball</code> Jenkins job to complete. Once it does, you may proceed.<br />
<br />
==Update Documentation==<br />
<br />
Let's update the FreeM documentation on the website. To do so, run the following command in the root of the <code>freem</code> repository:<br />
<br />
<pre><br />
$ scripts/upload-docs jpw@freem.coherent-logic.com<br />
</pre><br />
<br />
==Build Distribution Packages==<br />
<br />
===Solaris/Illumos===<br />
* Connect to the following machines:<br />
** yuna<br />
** bh-openindiana-amd64-01<br />
** bh-sol10-amd64-01<br />
* On each of the above machines, do the following:<br />
** Update the FreeM CVS repo<br />
** Do a clean rebuild of the source (installation not necessary)<br />
** Generate the package: <code>./mk-solaris-package ''architecture'' ''OS''</code><br />
** Upload the package: <code>scp CLDfreem-maj.min.patch-osMaj.Min-arch.pkg jpw@freem.coherent-logic.com://var/www/freem.coherent-logic.com/downloads/binaries/''os''/''os-version''/</code><br />
<br />
===NetBSD pkgsrc-wip===<br />
* Connect to <code>eucleia</code><br />
* Navigate to <code>/usr/pkgsrc/wip</code><br />
* Run <code>git pull -r</code><br />
* Navigate to <code>/usr/pkgsrc/wip/freem</code><br />
* Update <code>COMMIT_MSG</code><br />
* Update the <code>DISTNAME=</code> field in <code>Makefile</code> with the new version information<br />
* Run <code>make distinfo</code><br />
* Run <code>pkglint -e</code> to check for errors<br />
* Once <code>pkglint</code> comes back clean, commit everything (<code>git commit -a</code>) using the following commit message as a template:<br />
<pre><br />
freem: Update to major.minor.patch<br />
<br />
Packaging changes:<br />
* <changes-to-pkgsrc-packaging><br />
<br />
Upstream changes:<br />
* <Contents-of-ChangeLog><br />
</pre><br />
* Run <code>git push</code><br />
<br />
===Debian GNU/Linux===<br />
<br />
* Update ''debian/changelog'' in the ''freem-mk-debian-package'' repository with the correct versioning information and commit to CVS<br />
* Connect to the following machines:<br />
** bh-deb12-amd64-01<br />
** bh-deb12-i386-01<br />
** dryades<br />
** hybris<br />
* On each machine, go to <code>~/development/freem-mk-debian-package</code> and run the following commands:<br />
<pre><br />
$ cvs update -Pd<br />
$ ./mk-debian-package ''maj.min.patch pkg-version'' jpw@freem.coherent-logic.com<br />
</pre><br />
* Connect to <code>packages.clogic-int.com</code><br />
* Run the following commands to get the new release packages signed and into the repository:<br />
<pre><br />
$ fradd ''maj.min.patch pkg-ver'' amd64<br />
$ fradd ''maj.min.patch pkg-ver'' armhf<br />
$ fradd ''maj.min.patch pkg-ver'' i386<br />
$ fradd ''maj.min.patch pkg-ver'' arm64<br />
</pre><br />
<br />
==Update Wiki==<br />
* Generate a Release Notes page for this version on freem-wiki.coherent-logic.com<br />
<br />
==Announce Release==<br />
* Post to <code>freem-users</code> and <code>freem-dev</code> mailing lists<br />
* Post to Discord <br />
* Post to Facebook<br />
* Post to LinkedIn<br />
* Post to <code>comp.lang.mumps</code><br />
<br />
==Spot Test Tier 2 Ports==<br />
This includes ports like OpenBSD and SCO OpenServer.<br />
<br />
==Prepare to Resume Development==<br />
Once the release cycle is done, run the following command in the root of the FreeM repository to set the version back to <code>cvs-current</code>:<br />
<pre><br />
$ scripts/set-version cvs-current<br />
</pre><br />
And then commit back to CVS.</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Template:InternalUseFeature&diff=370Template:InternalUseFeature2025-03-28T13:01:04Z<p>Smw: Created page with "{{Box|''This article documents a procedure intended for internal use by members of the FreeM team. It probably lacks utility for most users and developers.''}} Category:Inte..."</p>
<hr />
<div>{{Box|''This article documents a procedure intended for internal use by members of the FreeM team. It probably lacks utility for most users and developers.''}}<br />
[[Category:Internal Use]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=FreeM_0.62.3&diff=369FreeM 0.62.32025-03-28T04:39:48Z<p>Smw: /* Packaging */</p>
<hr />
<div>== Overview ==<br />
FreeM 0.62.3 was released on March 27, 2025<br />
<br />
== Changes ==<br />
<br />
=== Fix OO regression in method dispatch ===<br />
The method dispatch code now has the following improvements:<br />
* Method tag parsing skips comments, fixing a regression in inheritance scanning<br />
* When any method is called, its class (routine name) is stored in a memory index, preventing the process from having to walk the inheritance chain on subsequent calls to the method, improving dispatch performance<br />
* <code>%STRING</code> and <code>%SYSOOP</code> are cached this way automatically as soon as a FreeM process launches<br />
<br />
=== Fix port for SCO OpenServer ===<br />
Fixed all the bit rot in this port and made it work for the first time in a couple of years<br />
<br />
=== Fix port for Tru64 UNIX ===<br />
Made Tru64 work by reverting to global-backed SSVNs on this system<br />
<br />
=== Port to OS/2 4.52+ ===<br />
Requires the full GCC toolchain; tested only on ArcaOS 5.1.<br />
<br />
This port required using the OS/2-native <code>DosCopy</code> API instead of FreeM's internal file copy function (I should not have had to implement file copy myself to begin with, and it's utterly brain dead for an OS not to have this functionality built-in; I'm talking to you, UNIX!)<br />
<br />
Currently, the OS/2 port only supports one environment with one daemon and a single interpreter instance.<br />
<br />
Work is in progress to create an RPM package for FreeM on OS/2, just need to resolve some linker errors and gain access to the OS/2 World forums or some community where I can ask questions.<br />
<br />
=== RPM Packaging ===<br />
We now ship binary packages of FreeM in RPM and SRPM formats; tested on Rocky Linux 9 and Fedora 41 (should work on RHEL as well)<br />
<br />
=== Make systemd units friendlier to RPM packaging ===<br />
Including more init scripts in the source distribution of FreeM was necessary for RPM packaging<br />
<br />
<br />
== Packaging ==<br />
<br />
FreeM 0.62.3 is natively packaged for:<br />
<br />
* Solaris 5.8 on 64-bit SPARC<br />
* Solaris 5.10 on 64-bit Intel<br />
* OpenIndiana Hipster 5.11 on 64-bit Intel<br />
* Debian Bookworm, Bullseye, and Trixie on amd64, i386, armhf, and arm64<br />
* Ubuntu Noble and Oracular on amd64, armhf, and arm64<br />
* NetBSD <code>pkgsrc-wip</code><br />
* Fedora 41/Rocky Linux 9 (should work on other Red Hat derivatives as well)<br />
<br />
== Links ==<br />
* Downloads: [https://freem.coherent-logic.com/downloads.cfm https://freem.coherent-logic.com/downloads.cfm]<br />
* Documentation: [https://freem.coherent-logic.com/docs/0.62.3/freem.html https://freem.coherent-logic.com/docs/0.62.3/freem.html]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Main_Page&diff=368Main Page2025-03-28T04:35:54Z<p>Smw: /* Release Notes */</p>
<hr />
<div>This wiki contains documentation not included in the [https://freem.coherent-logic.com/docs FreeM Manual], including platform-specific installation and configuration notes, project policies, technical deep-dives, and release notes.<br />
<br />
== Release Notes ==<br />
* [[Conformance Clause]]<br />
* [[FreeM 0.62.3]]<br />
* [[FreeM 0.62.2]]<br />
* [[FreeM 0.62.1]]<br />
* [[FreeM Lite]]<br />
* [[FreeM 0.59.2]]<br />
<br />
== Project Policies and Procedures ==<br />
* [[General Policies]]<br />
* [[Code of Conduct]]<br />
* [[Contributor Guide]]<br />
* [[Release Procedure]]<br />
<br />
== Port Tiers ==<br />
* [[Port Tiers]]<br />
* [[:Category:Tier 1 Ports|Tier 1 Ports]]<br />
* [[:Category:Tier 2 Ports|Tier 2 Ports]]<br />
* [[:Category:Tier 3 Ports|Tier 3 Ports]]<br />
<br />
== Platform Notes ==<br />
=== Tier 1 Ports ===<br />
* [[Platform Notes (Solaris/Illumos)]]<br />
* [[Platform Notes (NetBSD)]]<br />
* [[Platform Notes (FreeBSD)]]<br />
* [[Platform Notes (GNU/Linux)]]<br />
* [[Platform Notes (OpenBSD)]]<br />
<br />
=== Tier 2 Ports ===<br />
* [[Platform Notes (OS/2)]]<br />
* [[Platform Notes (SCO OpenServer)]]<br />
* [[Platform Notes (Compaq Tru64 UNIX)]]<br />
* [[Platform Notes (IBM AIX)]]<br />
<br />
=== Tier 3 Ports ===<br />
* [[Platform Notes (GNU HURD)]]<br />
* [[Platform Notes (SGI IRIX)]]<br />
* [[Platform Notes (HP-UX)]]<br />
* [[Platform Notes (Mac OS X)]]<br />
* [[Platform Notes (Minix 3+)]]<br />
<br />
== Tips and Tricks ==<br />
* [[Subscript Rules (Local and Global)]]<br />
* [[Object-Oriented Programming in FreeM]]<br />
<br />
== Technical Deep-Dives ==<br />
* [[FreeM System Architecture]]<br />
* [[Event Handling in FreeM]]<br />
* [[FreeM Transaction Processing Architecture]]<br />
* [[What is the GUMP?]]<br />
* [[Namespace Rules]]<br />
* [[Routine and Global Search Path Internals]]<br />
<br />
== History ==<br />
* [[FreeM History]]<br />
* [[Original README from Shalom ha-Ashkenaz]]<br />
<br />
== Status of Popular M Applications in FreeM ==<br />
<br />
* [[Applications: VA VistA]]<br />
* [[Applications: VA FileMan]]<br />
* [[Applications: VPE (Victory Programming Environment)]]<br />
* [[Applications: M Web Server]]<br />
* [[Applications: GDS/JDS]]<br />
* [[Applications: MVTS (M Validation and Test Suite)]]<br />
<br />
== General M Topics ==<br />
* [[M User's Group]]<br />
* [[M Technology Association]]<br />
* [[M Development Committee]]<br />
* [[Cache and M Technology Association UK]]<br />
* [[M User's Group-Deutschland]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=FreeM_0.62.3&diff=367FreeM 0.62.32025-03-28T04:35:31Z<p>Smw: /* Port to OS/2 4.52+ */</p>
<hr />
<div>== Overview ==<br />
FreeM 0.62.3 was released on March 27, 2025<br />
<br />
== Changes ==<br />
<br />
=== Fix OO regression in method dispatch ===<br />
The method dispatch code now has the following improvements:<br />
* Method tag parsing skips comments, fixing a regression in inheritance scanning<br />
* When any method is called, its class (routine name) is stored in a memory index, preventing the process from having to walk the inheritance chain on subsequent calls to the method, improving dispatch performance<br />
* <code>%STRING</code> and <code>%SYSOOP</code> are cached this way automatically as soon as a FreeM process launches<br />
<br />
=== Fix port for SCO OpenServer ===<br />
Fixed all the bit rot in this port and made it work for the first time in a couple of years<br />
<br />
=== Fix port for Tru64 UNIX ===<br />
Made Tru64 work by reverting to global-backed SSVNs on this system<br />
<br />
=== Port to OS/2 4.52+ ===<br />
Requires the full GCC toolchain; tested only on ArcaOS 5.1.<br />
<br />
This port required using the OS/2-native <code>DosCopy</code> API instead of FreeM's internal file copy function (I should not have had to implement file copy myself to begin with, and it's utterly brain dead for an OS not to have this functionality built-in; I'm talking to you, UNIX!)<br />
<br />
Currently, the OS/2 port only supports one environment with one daemon and a single interpreter instance.<br />
<br />
Work is in progress to create an RPM package for FreeM on OS/2, just need to resolve some linker errors and gain access to the OS/2 World forums or some community where I can ask questions.<br />
<br />
=== RPM Packaging ===<br />
We now ship binary packages of FreeM in RPM and SRPM formats; tested on Rocky Linux 9 and Fedora 41 (should work on RHEL as well)<br />
<br />
=== Make systemd units friendlier to RPM packaging ===<br />
Including more init scripts in the source distribution of FreeM was necessary for RPM packaging<br />
<br />
<br />
== Packaging ==<br />
<br />
FreeM 0.62.3 is natively packaged for:<br />
<br />
* Solaris 5.8 on 64-bit SPARC<br />
* Solaris 5.10 on 64-bit Intel<br />
* OpenIndiana Hipster 5.11 on 64-bit Intel<br />
* Debian Bookworm, Bullseye, and Trixie on amd64, i386, armhf, and arm64<br />
* Ubuntu Noble and Oracular on amd64, armhf, and arm64<br />
* NetBSD <code>pkgsrc-wip</code><br />
* Fedora 41/Rocky Linux 9 (should also work on other Red Hat derivatives as well)<br />
<br />
== Links ==<br />
* Downloads: [https://freem.coherent-logic.com/downloads.cfm https://freem.coherent-logic.com/downloads.cfm]<br />
* Documentation: [https://freem.coherent-logic.com/docs/0.62.3/freem.html https://freem.coherent-logic.com/docs/0.62.3/freem.html]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=FreeM_0.62.3&diff=366FreeM 0.62.32025-03-28T04:31:34Z<p>Smw: Created page with "== Overview == FreeM 0.62.3 was released on March 27, 2025 == Changes == === Fix OO regression in method dispatch === The method dispatch code now has the following improvem..."</p>
<hr />
<div>== Overview ==<br />
FreeM 0.62.3 was released on March 27, 2025<br />
<br />
== Changes ==<br />
<br />
=== Fix OO regression in method dispatch ===<br />
The method dispatch code now has the following improvements:<br />
* Method tag parsing skips comments, fixing a regression in inheritance scanning<br />
* When any method is called, its class (routine name) is stored in a memory index, preventing the process from having to walk the inheritance chain on subsequent calls to the method, improving dispatch performance<br />
* <code>%STRING</code> and <code>%SYSOOP</code> are cached this way automatically as soon as a FreeM process launches<br />
<br />
=== Fix port for SCO OpenServer ===<br />
Fixed all the bit rot in this port and made it work for the first time in a couple of years<br />
<br />
=== Fix port for Tru64 UNIX ===<br />
Made Tru64 work by reverting to global-backed SSVNs on this system<br />
<br />
=== Port to OS/2 4.52+ ===<br />
Requires the full GCC toolchain; tested only on ArcaOS 5.1<br />
<br />
=== RPM Packaging ===<br />
We now ship binary packages of FreeM in RPM and SRPM formats; tested on Rocky Linux 9 and Fedora 41 (should work on RHEL as well)<br />
<br />
=== Make systemd units friendlier to RPM packaging ===<br />
Including more init scripts in the source distribution of FreeM was necessary for RPM packaging<br />
<br />
<br />
== Packaging ==<br />
<br />
FreeM 0.62.3 is natively packaged for:<br />
<br />
* Solaris 5.8 on 64-bit SPARC<br />
* Solaris 5.10 on 64-bit Intel<br />
* OpenIndiana Hipster 5.11 on 64-bit Intel<br />
* Debian Bookworm, Bullseye, and Trixie on amd64, i386, armhf, and arm64<br />
* Ubuntu Noble and Oracular on amd64, armhf, and arm64<br />
* NetBSD <code>pkgsrc-wip</code><br />
* Fedora 41/Rocky Linux 9 (should also work on other Red Hat derivatives as well)<br />
<br />
== Links ==<br />
* Downloads: [https://freem.coherent-logic.com/downloads.cfm https://freem.coherent-logic.com/downloads.cfm]<br />
* Documentation: [https://freem.coherent-logic.com/docs/0.62.3/freem.html https://freem.coherent-logic.com/docs/0.62.3/freem.html]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(OS/2)&diff=365Platform Notes (OS/2)2025-03-28T04:09:59Z<p>Smw: /* Verified Releases */</p>
<hr />
<div>{{DevBranchFeature}}<br />
<br />
== Port Status ==<br />
OS/2 is a [[Tier 2 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM cvs-current (23 Mar 2025)<br />
<br />
== Testing Details ==<br />
We build and test the OS/2 port on an ArcaOS 5.1 VM running in VirtualBox.<br />
<br />
== Building and Installing ==<br />
Currently, the OS/2 port is only tested on ArcaOS, and you will need to install several things in order to build and run:<br />
<br />
* autoconf<br />
* automake<br />
* gcc<br />
* readline-devel<br />
* bash<br />
* binutils-devel<br />
* coreutils<br />
* emxrt<br />
* gawk<br />
* gcc-wlink<br />
* gcc-wrt<br />
* grep<br />
* info<br />
* libc-devel<br />
* libtool<br />
* kbuild-make<br />
* sed<br />
* tar<br />
* gzip<br />
<br />
All of these can be installed with <code>yum install</code> or the Arca Noae Package Manager (ANPM).<br />
<br />
Once the dependencies are met, simply download and extract the FreeM source code, and follow these steps:<br />
<br />
* Open an OS/2 Window (in the Command Prompts folder in OS/2 System or Computer on the desktop)<br />
* Run the following commands:<br />
<pre><br />
[C:\] bash<br />
$ autoreconf --install # only needed if installing from the CVS repo<br />
$ ./configure CC=gcc GREP=grep<br />
$ make<br />
$ make install<br />
$ fmadm configure<br />
</pre><br />
<br />
Once this is done, proceed to the next section.<br />
<br />
== Workarounds ==<br />
Under OS/2 and ArcaOS, FreeM binaries are installed under <code>C:\USR\LOCAL\BIN</code>, but the FreeM daemon and the FreeM interpreter cannot be launched from the same executable (the daemon will start, but interpreters will give an error resembling <code>Resource busy</code>).<br />
<br />
The <code>fmadm configure</code> (and <code>fmadm reconfigure</code>) commands will automatically copy <code>C:\USR\LOCAL\BIN\freem.exe</code> to <code>C:\USR\LOCAL\BIN\freemd.exe</code>.<br />
<br />
== Running ==<br />
# Open an OS/2 Window command prompt<br />
# Run <code>bash</code><br />
# Run <code>/usr/local/bin/freemd -dk</code> to start the FreeM daemon<br />
# Minimize the FreeM daemon process<br />
# Open a second OS/2 Window command prompt<br />
# Run the following commands:<br />
<pre><br />
[C:\] CD \USR\LOCAL\BIN<br />
[C:\USR\LOCAL\BIN] FREEM<br />
</pre><br />
<br />
== Platform Limitations ==<br />
* Only one interpreter instance can be launched at a time<br />
* <code>JOB</code> does not work<br />
* Terminal windows are fixed in size to 80x24<br />
* The FreeM daemon must be launched in the foreground, as <code>fork()</code> is unsupported here (<code>freemd.exe</code> will refuse to launch if you do not pass the <code>-k</code> or <code>--nofork</code> flags).<br />
* Network sockets functionality is unavailable<br />
* Building without <code>readline</code> causes direct mode to echo each line of code entered<br />
* No binary package is available: once we have an RPM package for Red Hat-derived distributions, an OS/2 RPM should be fairly straightforward<br />
<br />
Documentation for porting UNIX applications to OS/2 is scant, which makes many of these issues difficult to work around. However, we do want to iron out all of these shortcomings and promote this port to Tier 1 status.<br />
<br />
== Required Kernel Tuning ==<br />
Coming soon.<br />
<br />
[[Category: Tier 2 Ports]]<br />
[[Category: Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(SCO_OpenServer)&diff=364Platform Notes (SCO OpenServer)2025-03-28T04:09:35Z<p>Smw: /* Verified Releases */</p>
<hr />
<div>== Port Status ==<br />
<br />
SCO OpenServer is a [[Tier 2 Port]]<br />
<br />
== Verified Releases ==<br />
* 0.62.3 (27 Mar 2025)<br />
* 0.62.2 (25 Mar 2025)<br />
* 0.56.2 (4 Aug 2023)<br />
<br />
== Build Details ==<br />
You will need to set the <code>ACCEPT_INFERIOR_RM_PROGRAM</code> environment variable to <code>yes</code> before running <code>configure</code> if GNU <code>coreutils</code> is not installed. An invocation such as the following should be sufficient:<br />
$ export ACCEPT_INFERIOR_RM_PROGRAM=yes<br />
$ ./configure MAKE=/usr/gnu/bin/gmake GAWK=/usr/gnu/bin/gawk<br />
<br />
== Testing Details ==<br />
<br />
We build and test the SCO OpenServer port on a system with the following specifications:<br />
<br />
* ESXi Virtual Machine<br />
* SCO OpenServer 5.0.7<br />
* gcc v2.95.3<br />
* autoconf 2.54<br />
* automake 1.7.1<br />
<br />
This port requires significant manual intervention to build, given the old version of GNU autotools in play.<br />
<br />
== Required Kernel Tuning ==<br />
<br />
You must set the maximum size of a shared memory segment to at least 17000000. This can be accomplished with the <code>scoadmin</code> utility.<br />
<br />
Once this parameter is adjusted, you must re-link the kernel, also from <code>scoadmin</code>.<br />
<br />
== Port Challenges ==<br />
<br />
The build system presents significant challenges.<br />
<br />
<br />
[[Category: Tier 2 Ports]]<br />
[[Category: Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(Compaq_Tru64_UNIX)&diff=363Platform Notes (Compaq Tru64 UNIX)2025-03-28T04:09:16Z<p>Smw: /* Verified Releases */</p>
<hr />
<div>== Port Status ==<br />
<br />
Compaq Tru64 UNIX is a [[Tier 2 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* <code>cvs-current</code> (26 Mar 2025) (builds and runs cleanly, but will use global-backed SSVNs)<br />
<br />
FreeM 0.62.2 builds, but errors out when launching the daemon:<br />
freem [FATAL]: memory allocation failure in symtab_init [errno 0 Successful]<br />
<br />
There is an issue on this at https://bugs.coherent-logic.com/view.php?id=16<br />
<br />
== Testing Details ==<br />
<br />
We build and test the Tru64 UNIX port on a system with the following specifications:<br />
<br />
* Alpha EV67-based host<br />
* Compaq Tru64 UNIX 5.1b<br />
* GNU gcc v4.7.7<br />
* GNU autoconf 2.71<br />
* GNU automake 1.16.4<br />
<br />
This port should theoretically run on DEC OSF/1 or Digital UNIX, given a compatible GNU toolchain, but we do not have the resources to test such configurations.<br />
<br />
== Required Kernel Tuning ==<br />
<br />
For the default daemon configuration, you will need a kernel <code>shm_max</code> parameter of at least 16795968. We recommend 17000000.<br />
<br />
To apply an shm_max of 17000000, you will need to do the following:<br />
<br />
* Gain root privileges on your system<br />
* Create a file called "pstanza" with the following data:<br />
ipc:<br />
shm_max = 17000000<br />
* If no <code>shm_max</code> parameter exists in <code>/etc/sysconfigtab</code>:<br />
# sysconfigdb -a -f pstanza ipc<br />
* If a previous <code>shm_max</code> configuration exists:<br />
# sysconfigdb -m -f pstanza ipc<br />
* Reboot the system<br />
<br />
<br />
[[Category: Tier 2 Ports]]<br />
[[Category: Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(NetBSD)&diff=362Platform Notes (NetBSD)2025-03-28T04:08:36Z<p>Smw: /* Verified Releases */</p>
<hr />
<div>== Port Status ==<br />
NetBSD is a [[Tier 1 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM 0.62.2 (23 Mar 2025)<br />
* FreeM cvs-current<br />
* FreeM 0.62.1 (14 Mar 2025)<br />
* FreeM 0.59.0 (04 Aug 2023)<br />
<br />
== Testing Details ==<br />
<br />
* Proxmox Virtual Machine (64-bit)<br />
* NetBSD/amd64 10.0<br />
* gcc v10.5.0<br />
* autoconf 2.72<br />
* automake 1.16.5<br />
<br />
[[Category:Platform Notes]]<br />
[[Category:Tier 1 Ports]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(GNU/Linux)&diff=361Platform Notes (GNU/Linux)2025-03-28T04:08:18Z<p>Smw: /* Verified Releases */</p>
<hr />
<div>== Port Status ==<br />
The GNU/Linux port is a [[Tier 1 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM <code>cvs-current</code><br />
* FreeM 0.62.1 (14 Mar 2025)<br />
* FreeM 0.61.2<br />
* FreeM 0.59.2 (04 Aug 2023)<br />
<br />
== Testing Details ==<br />
<br />
We build and test the GNU/Linux port on a system with the following specifications:<br />
<br />
* amd64-based host<br />
* Arch Linux running the 6.12.18-1-lts Linux kernel<br />
* GNU gcc v14.2.1<br />
* GNU autoconf 2.72<br />
* GNU automake 1.17<br />
<br />
== Required Kernel Tuning ==<br />
<br />
For the default daemon configuration, you will need a <code>kernel.shmmax</code> parameter of at least <code>6000000</code>.<br />
<br />
To check the current value of this kernel parameter, enter the following command:<br />
<pre><br />
$ sudo sysctl kernel.shmmax<br />
</pre><br />
<br />
If the reported value is less than 6000000, continue with the following procedure. Otherwise, your system already meets the requirements for running FreeM in the default configuration.<br />
<br />
To apply an <code>shm_max</code> of <code>6000000</code>, you will need to do the following:<br />
<br />
* Create a file called <code>10-shmmax.conf</code> in <code>/etc/sysctl.d</code>, containing the following information:<br />
<pre><br />
kernel.shmmax = 6000000<br />
</pre><br />
<br />
* Reboot your system<br />
<br />
== Installing on Debian GNU/Linux and derivatives ==<br />
<br />
=== Repository Installation ===<br />
On recent releases of Debian (Bullseye, Bookworm, and Trixie) and Ubuntu (Noble Numbat and Oracular Oriole), you can use the [https://packages.coherent-logic.com Coherent Logic Package Repository] to install pre-built binary packages for <code>amd64</code>, <code>armhf</code>, and <code>arm64</code> architectures.<br />
<br />
# Follow the instructions at [https://packages.coherent-logic.com https://packages.coherent-logic.com] to set up your computer for use with our package repository<br />
# Run <code>sudo apt install freem</code> to install FreeM<br />
<br />
=== Direct Package Installation ===<br />
# Download the appropriate package from [https://freem.coherent-logic.com/binaries.cfm https://freem.coherent-logic.com/binaries.cfm]<br />
# Install the package with <code>sudo dpkg -i &lt;package-file&gt;</code>, substituting the name of the downloaded file for <code>&lt;package-file&gt;</code><br />
<br />
== Starting the FreeM Daemon Automatically ==<br />
<br />
=== systemd ===<br />
<br />
To start the FreeM daemon automatically with systemd, you will need to first decide if you want the daemon to run as a system-level service, or as a user service under your normal user account.<br />
<br />
==== System-Level Service ====<br />
<br />
* Copy <code>scripts/systemd/system/freem.service</code> from the FreeM distribution to <code>/etc/systemd/system</code><br />
<br />
# Type the following commands as root:<br />
## <code>groupadd freem</code><br />
## <code>useradd -m -d /home/freem -g freem freem</code><br />
# Type the following command for each user who will use FreeM, substituting the user's login name for <code>username</code>:<br />
## <code>usermod -aG freem ''username''</code><br />
# Type the following commands as root:<br />
## <code>systemctl daemon-reload</code><br />
## <code>systemctl enable freem</code><br />
## <code>systemctl start freem</code><br />
# You may then check the status of the daemon with the following command:<br />
## <code>systemctl status freem</code><br />
<br />
If the third line of output contains the text <code>active (running)</code>, the service has been successfully configured and started.<br />
<br />
==== User-Level Service ====<br />
<br />
# Copy <code>scripts/systemd/user/freem.service</code> from the FreeM distribution to <code>$HOME/.config/systemd/user</code><br />
# Type the following commands:<br />
<pre><br />
$ systemctl --user enable freem<br />
$ systemctl --user start freem<br />
</pre><br />
# You may then check the status of the daemon with the following command:<br />
<pre><br />
$ sudo systemctl --user status freem<br />
</pre><br />
<br />
If the third line of output contains the text <code>active (running)</code>, the service has been successfully configured and started.<br />
<br />
=== sysvinit ===<br />
Coming soon.<br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(FreeBSD)&diff=360Platform Notes (FreeBSD)2025-03-28T04:07:58Z<p>Smw: /* Verified Releases */</p>
<hr />
<div>== Port Status ==<br />
FreeBSD is a [[Tier 1 Port]]<br />
<br />
== Verified Releases ==<br />
* FreeM 0.62.3 (27 Mar 2025)<br />
* FreeM 0.62.2 (23 Mar 2025)<br />
* FreeM <code>cvs-current</code><br />
* FreeM 0.62.1<br />
<br />
== Testing Details ==<br />
* Bare-metal amd64 system<br />
* FreeBSD 14.1-RELEASE-p2 amd64<br />
* gcc 13.2.0<br />
* autoconf 2.72<br />
* automake 1.17<br />
<br />
== Required Kernel Tuning ==<br />
Coming soon<br />
<br />
== Starting Daemon Automatically ==<br />
* Copy <code>scripts/freebsd-rc/freem</code> to <code>/usr/local/etc/rc.d</code><br />
* Type the following commands with root privileges:<br />
# pw group add freem<br />
# pw user add freem -m -g freem<br />
# sysrc freem_enable="YES"<br />
# chmod +x /usr/local/etc/rc.d/freem<br />
* For each user who needs to run FreeM, type the following command:<br />
# pw group mod freem -m ''username''<br />
* Reboot <br />
<br />
== Port Challenges ==<br />
None.<br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smwhttps://freem-wiki.coherent-logic.com/index.php?title=Platform_Notes_(Solaris/Illumos)&diff=359Platform Notes (Solaris/Illumos)2025-03-28T04:07:27Z<p>Smw: /* Verified Releases */</p>
<hr />
<div>== Port Category ==<br />
<br />
The Solaris port is a [[Tier 1 Port]], and Solaris 8 on 64-bit SPARC is the platform where primary development occurs.<br />
<br />
== Verified Releases ==<br />
* 0.62.3 (Solaris 5.8 sparc64, Solaris 5.10 i86pc, Solaris 5.11 i86pc, Solaris 5.11 sparc64, OpenIndiana Hipster 5.11 amd64, 27 Mar 2025<br />
* 0.62.2 (Solaris 5.8 sparc64, Solaris 5.10 i86pc, Solaris 5.11 i86pc, Solaris 5.11 sparc64, OpenIndiana Hipster 5.11 amd64, 23 Mar 2025)<br />
* 0.62.1 (Solaris 5.10 i86pc, 17 Mar 2025)<br />
* <code>cvs-current</code> (Solaris 5.8 sparc64, Solaris 11.4 sparc64 and i86pc)<br />
* 0.62.1 (Solaris 5.8 sparc64, Solaris 11.4 sparc64 and i86pc, OpenIndiana Hipster, 16 Mar 2025)<br />
* 0.61.2 (Solaris 5.8 sparc64, Solaris 11.4 sparc64 and i86pc)<br />
* 0.59.0 (Solaris 10 sparc64, 4 Aug 2023)<br />
* 0.59.0 (Solaris 7 sparc32, 4 Aug 2023)<br />
* 0.59.0 (Solaris 11.4 i86pc, 4 Aug 2023)<br />
* 0.57.0 (Solaris 11.3 sparc64, 4 Aug 2023)<br />
<br />
== Build Notes ==<br />
=== Solaris 7 ===<br />
* If using the old <code>sunfreeware.com</code> GNU toolchain packages on Solaris 7, you will need the latest <code>7_Recommended.zip</code> patch cluster.<br />
* The <code>mktemp</code> utility may lock up several times during the <code>configure</code> phase. If this happens, you may simply kill the process with <code>pkill -9 mktemp</code>. This does not appear to harm the build.<br />
<br />
=== Solaris 8 ===<br />
<br />
==== Binary Packages ====<br />
On Solaris 8, you can install a binary release:<br />
<br />
<pre><br />
$ sudo pkgadd -d CLDfreem-<version>-solaris5.8-sparcv9.pkg<br />
</pre><br />
<br />
Once this is done, add yourself to the <code>freem</code> group:<br />
# Open <code>/etc/group</code> as <code>root</code> in your favorite text editor<br />
# Find the line beginning with <code>freem</code><br />
# Append your username to the end of that line<br />
# Save the file<br />
# Exit the editor<br />
<br />
Now, you can start the FreeM daemon as follows:<br />
<br />
<pre><br />
$ sudo /etc/init.d/freem start<br />
</pre><br />
<br />
==== Building From Source ====<br />
You will need the latest <code>8_Recommended.zip</code> patch cluster for Solaris, as well as:<br />
<br />
* gcc (3.4 or higher recommended)<br />
* autoconf<br />
* automake<br />
* libtool<br />
* texinfo<br />
* readline (recommended but not strictly required)<br />
<br />
=== Solaris 9 ===<br />
TBD<br />
<br />
=== Solaris 10 ===<br />
TBD<br />
<br />
=== Solaris 11 ===<br />
We build with the IPS packages for the GNU toolchain here. The Sun C compiler can also be used here (at least the version from Developer Studio 12.6).<br />
<br />
==== Necessary Packages ====<br />
<code><br />
$ sudo pkg install gcc automake autoconf gnu-make git readline libtool texinfo ncurses<br />
</code><br />
<br />
==== Dealing with ncurses ====<br />
You will need to tell the configure script not to bother with the wide-character ncurses library (does not apply to releases later than 0.61.2):<br />
<br />
<code><br />
$ ./configure --without-ncursesw<br />
</code><br />
<br />
=== OpenIndiana ===<br />
==== Binary Packages ====<br />
On OpenIndiana, you can install a binary release:<br />
<br />
<pre><br />
$ sudo pkgadd -d CLDfreem-<version>-openindiana5.11-amd64.pkg<br />
</pre><br />
<br />
Once this is done, add yourself to the <code>freem</code> group, and start the FreeM daemon as follows:<br />
<br />
<pre><br />
$ sudo /etc/init.d/freem start<br />
</pre><br />
==== Building From Source ====<br />
See instructions for [[#Solaris 11|Solaris 11]], but with the exception that <code>configure</code> must be run as follows:<br />
<pre><br />
$ ./configure MAKE=gmake<br />
</pre><br />
<br />
== Testing Details ==<br />
<br />
We build and test the Solaris port of FreeM on the following systems:<br />
<br />
=== Sun Ultra 10 ===<br />
<br />
* Sun Ultra 10 with a 400MHz UltraSPARC-IIi CPU (64-bit)<br />
* 640MB RAM<br />
* Solaris 5.8 Generic_117350-39<br />
* gcc v3.4.6<br />
* autoconf 2.69<br />
* automake 1.16.5<br />
<br />
=== Sun SPARCserver 20 ===<br />
<br />
* Sun SPARCserver 20 with dual 100MHz Ross HyperSPARC CPUs (32-bit)<br />
* 512MB RAM<br />
* Solaris 7 with the latest 7_Recommended.zip patch cluster applied (REQUIRED FOR SOLARIS 7)<br />
* gcc v3.4.6<br />
* autoconf 2.68<br />
* automake 1.11.1<br />
<br />
=== SunFire T2000 ===<br />
<br />
* Sun UltraSPARC T1 CPU (64-bit)<br />
* Solaris 10<br />
<br />
=== Oracle SPARC T4-1 ===<br />
* Oracle SPARC T4 CPU (64-bit)<br />
* Solaris 11.4 11.4.0.15.0<br />
* gcc v7.3.0<br />
* autoconf 2.69<br />
* automake 1.15<br />
* Oracle Developer Studio 12.6 (SunCC compiler)<br />
<br />
=== x86 VM ===<br />
* Solaris 11.4 11.4.0.15.0<br />
* gcc v7.3.0<br />
* autoconf 2.69<br />
* automake 1.15<br />
<br />
=== OpenIndiana (Illumos) ===<br />
<br />
* Proxmox VM<br />
* OpenIndiana Hipster 5.11 illumos-053feb1540<br />
* gcc 14.2.0<br />
* autoconf 2.72<br />
* automake 1.16.5<br />
<br />
<br />
This port should theoretically run on any Solaris or Illumos machine running Solaris 7 or newer.<br />
<br />
== Required Kernel Tuning ==<br />
<br />
=== Solaris 11 ===<br />
TBD<br />
<br />
=== Solaris 8 ===<br />
Append the following to <code>/etc/system</code> and reboot:<br />
<br />
<pre><br />
set shmsys:shminfo_shmmax = 67108864<br />
set shmsys:shminfo_shmmni = 0x1000<br />
set shmsys:shminfo_shmseg = 0x100<br />
</pre><br />
<br />
== Starting FreeM Daemon Automatically ==<br />
<br />
These instructions apply only to source builds. The binary packages install the init script automatically.<br />
<br />
* Copy <code>scripts/solaris-init/freem</code> to <code>/etc/init.d</code><br />
* Make a symbolic link from <code>/etc/rc3.d/S20freem</code> to <code>/etc/init.d/freem</code><br />
* Run <code>/etc/init.d/freem start</code><br />
<br />
[[Category:Tier 1 Ports]]<br />
[[Category:Platform Notes]]</div>Smw