GerH source distro at hebbut.net: HOW TO compile/compare/merge for Bill et al

"Ger Hobbelt" <[email protected]>
Newsgroups gmane.mail.spam.crm114
Message-ID <[email protected]> 
Consider this the QUICKREF/HOWTO for when you like to:

- compare GerH source distros with Bill's wget copy (i.e. 'src/*' file
collection of e-ve-ry-thing)

- build GerH source distros 'The Bill Way'



Table of contents:

  Step 1: Downloading
  Step 2: 7-Zip
  Step 3: Extracting
  Step 4: Build From Source The Bill Way
  Step 5: You've got errors?
  Step 6: Megatest anyone?
  Step 4-alt: You want to compare source trees?



Information provided may be subject to change, depending on feedback
from BillY, so caveat emptor and all that.



----------------------------------------------------------------------------

Step 1: Downloading
==============

Download the source distro at

  http://www.hebbut.net/Public.Offerings/index.html#crm114

It's a '*.src.7z' archive.


Step 2: 7-Zip
==============

Install 7zip (www.7zip.org) if you haven't already.

If (on UNIX) you get to see a list of commandline options when you run

  7z

you're good to go.

On Windows, rightclick on a .7z file should provide you with a context
menu, where 7zip 'Extract...', etc. options are available.


Step 3: Extracting
===============

Extract the archive by running

(on UNIX)

  7z x crm114-20080325-BlameSentansoken-Ger-1954.src.7z      (or the
equivalent of the day)

(on Windows)

  rightclick, select '7-Zip' --> 'Extract here'

which will expand everything into a subdirectory tree, looking
somewhat like this:

  ./crm114-20080325-BlameSentansoken
     /docs
     /examples
     /m4
     /mailfilter
     /man
     /src
     /tests
     /win32


Step 4: Build From Source The Bill Way
=============================

'cd' to the /src/ directory in that subdirectory tree.

To mimic Bill's build, run this instead of basic 'make':

  make -f Makefile.BillY

or run the shell script

  make_BillY.sh

to achieve the same.

NOTE: the shell script is a very simple wrapper around that 'make ...'
incantation and can be used like you used 'make' itself before.
Running 'make' without the 'Makefile.BillY' will assume you've run the
configure script, which you didn't/don't/won't, so remember
to use

  make_BillY.sh

instead from here on out.


Step 5: You've got errors?
=====================

If there are any compile/build issues, you can look in these two places first:

Inspect the CFLAGS and LDFLAGS settings in

  Makefile.BillY

to see if they match your platform, just like you would otherwise have
to do so with BillY original Makefile.


WARNING: I test this setup on 64-bit UNIX, so be prepared to find that
I use a different set of LDFLAGS from the ones that come with BillY's
wget copy. Uncomment the proper line in Makefile.BillY accordingly.


Next, you may wish to tweak your configuration (remove certain
classifiers, exclude other features, ...) or you find that your
platform does not provide one of the run-time library/system calls the
default setup assumes you have: edit

  config_BillY.h

and '#define ... 1' or '#undef ...' each item according to your wishes
and platform system call availability.


When done, save & rerun Step 4 (build)


HINT: if you want to see what it's like for Win32 folks, diff this one
with ../win32/config_win32.h to see a completely different platform's
feature set.


NOTE: Portable code does NOT look/check for specific platforms,
compiler flags or other voodoo throughout the code base, but instead
_detects_ and/or _defines_ the available feature set in a _restricted_
set of files:

  config_BillY.h   -- configures ANY and ALL features of crm114
  config_BillY.h   -- _defines_ system library feature set
availability on a PER-ITEM (define, type, struct, call) basis
  crm114_sysincludes.h -- here's where all the voodoo magic is:
additional autodetecting and mix&merge with config_BillY.h driver. If
you don't know how to write cross-platform portable code, inspect
other code bases, such as, for example, OpenSSL (google that, it's
Open Source) or GCC (the sources! for the compiler), _before_ you run
and scream. This comes with no medicine and is NOT suitable for
first-year coders, if they like to live the Breezer life.

      For portability purposes, the source codebase will otherwise be
sprinkled with '#if defined(HAVE_xxxxxx)' compile-time checks where
applicable. Do NOT revert to using compiler/OS-specific #ifdef checks
instead: those will bite _someone_ (and that someone won't be you,
because it already worked at yours).

  crm_*_port*.c  -- files which provide OS-specific and/or generic
replacements, wrappers and extensions to be used by the crm114
software throughout

      For added bonus you should provide #else #error clauses in your
software to detect and report a feature missing on that
yet-undiscovered platform/OS/compiler combo. But that would be too
User Friendly, now would it?


  "And thus we end software porting class 101. Amen!", concludes vicar Ger.



Step 6: Megatest anyone?
================

on UNIX, you'll get to run megatest or megatest_ng (ng == Next
Generation) by running the equivalent 'make' incantation you used
before:

  make_BillY.sh magetest

or

  make_BillY.sh magetest_ng

OR (if you like so see 'make' itself on your command line):

  make -f Makefile.BillY megatest

or

  make -f Makefile.BillY megatest_ng

diff reports are shown like they ever were.


on Windows, run this:

  ( megatest.bat 2>&1 ) > megatest_win32_test.log

and view the diffs with

  megatest_knowngood.log

as provided in the distro or in your own reference directory using
KDiff3 or BC: see below (Step 4-alt) for these tools. Or run

  diff -u megatest_knowngood.log megatest_win32_test.log

as usual instead.




Step 4-alt: You want to compare source trees?
==================================

WARNING WARNING WARNING WARNING

Do NOT even consider trying 'diff'. That tool is nice, but it's line
based. ... So what?, you say. Several source files have quite a few
little changes ('sed -e s/<long-and-a-bit-of-magic>/int/g' comes to
mind; grep "INTifada" in ChangeLog) which do not show up in any
comprehensible way using a line-based console tool.

Instead, install KDiff3 on your UNIX box if you haven't already.

Windows users may consider purchasing and installing Beyond Compare
from Scooter Software, a.k.a. 'BC'. I did almost a decade ago and I
never looked back ever since.

Both these tools are:

- visual:    color aided for the brain impaired -- like _me_)
- character-based:   you'll see differences in source on a PER
CHARACTER/WORD basis, instead of simply marking whole lines without
any additional hints (as does Kompare for KDE, which has a bit nicer
visual SchnickSchnack IMHO, but here functionality is more important;
KDiff3 looks nice too and is (hopefully) improving where it is (IMO)
severely lacking compared to the Windows-based BC tool)

      END OF WARNING NOTICE

Use KDiff3 to select both the BillY wget source tree base directory

  BillY-wherever-wget/src/

and the /src/ directory of the extracted GerH src.7z:

  ./crm114-20080325-BlameSentansoken
     /src

and hit compare.



KDiff3 preference settings for best viewing:

  Configure-KDiff3 --> Diff icon --> tick the 'Try hard' checkbox


to merge, I use BC, but you might find a workflow suitable where you
Merge:Select everything from B and then Ctrl-ArrowDown through the
merge conflicts to exclude those changes you do not wish to have by
selecting A for those instead. This depends however on which directory
you specified for A, and which for B.
If you use KDiff3 on a regular basis, you probably know better than me
how to merge selected differences and all. Have fun.



------------------------------------------------------------------------------------------

Hope this is comprehensible and useful to some.


If you like stuff that works for you instead of the other way around,
go the './configure' way and 'make'.

Check this for the ./configure-savvy:


Basic 'I want a new crm':

  ./configure && make && make test


NOTE: I have NOT tested 'make install' as I consider that a security
issue: I run an *experimental* crm-filter setup and development on a
single box, so I got to be careful there. Sorry.



And when you want to generate a distro an' all or changed something
autocomfy and influential or just feel like you need a break:

  ./bootstrap && ./configure && make distclean && ./configure && make
&& make test && make distribution

and enjoy the backlog fireworks in your console window.



I like it.




DREAM: CUnit or other automated test harness for crm114 PLUS
mailfilter/mailreaver operational testing. Ahhhh... a man can dream.
How many interns would it take to get me this? Get me Lewinsky!








-- 
Met vriendelijke groeten / Best regards,

Ger Hobbelt

--------------------------------------------------
web: http://www.hobbelt.com/
 http://www.hebbut.net/
mail: [email protected]
mobile: +31-6-11 120 978
--------------------------------------------------

-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.