Questions about creating a port

[Alejandro Pulver]

On Thu, 17 Feb 2005 10:49:44 +0200
Peter Pentchev <roam at ringlet.net> wrote:

> On Wed, Feb 16, 2005 at 10:11:55PM +0100, Florent Thoumie wrote:
> > Alejandro Pulver wrote:
> > >Hello,
> > >
> > >I want to create a port of the modified version of 'generator' called 
> > >'generator-cbiere'.
> > >
> > >I partially made the port: it compiles and runs, but I have some questions 
> > >about the distribution, installation, patching, compiler warnings and type 
> > >decalrations.
> > >
> > >Distribution:
> > >
> > >The program is distributed by the author as a (complete) compressed 
> > >(tar/bz2) source called 'generator-0.35-cbiere.tar.bz2', or as a 
> > >compressed (bz2) patch called 'generator-0.35-cbiere.udiff.bz2' (that must 
> > >be applied to the original version of 'generator').
> > >
> > >Both are called in a non-standard format 
> > >("${PORTNAME}${PORTVERSION}-cbiere"), I think it should be 
> > >'generator-cbiere-0.35'. So (for using the complete source) I have to 
> > >change ${DISTFILES} (or ${DISTNAME} and ${EXTRACT_SUFX}) and ${WORKSRC}, 
> > >or upload that file to my server with the correct name.
> > >
> > >Which one is the best method to distribute the port (full source or 
> > >patch)? Can I include the patch (96386 bytes) directly in the 'files/' 
> > >directory of the port?
> > 
> > 	I'll use full source, and modify DISTFILES, try to use upstream 
> > 	sites.
> 
> I personally would also go for full sources, yes.
> 
> As to the distfile name, a better solution would be to modify just
> DISTNAME and then define USE_BZIP2 - see section 5.4.3, "EXTRACT_SUFX",
> in the Porter's Handbook.  The Good Thing(tm) about USE_BZIP2 is that it
> pulls archivers/bzip2 as a dependency if bzip2 is not part of the base
> system.  While bzip2 is indeed part of the base system on recent
> versions of FreeBSD, this is still the right way to do it for various
> reasons related to portability.
> 
> > >Installation:
> > >
> > >The program is installed as 'bin/generator-gtk', like 'generator' (the 
> > >original version), so they will conflict. How can I avoid this (I mean how 
> > >to rename the binary 'generator-gtk' to 'generator-cbiere-gtk')?
> > 
> > 	You can either set CONFLICTS or use in-line editing (USE_REINPLACE 
> > 	and
> > 	REINPLACE_CMD) to modify the Makefile so that it installs generator
> > 	binary under a different name.
> 
> If there is a case when both the 'generator' and 'generator-cbiere' MAY
> be installed simultaneously, then either REINPLACE_CMD or passing a
> --program-prefix or --program-suffix to a GNU configure-style script
> would be best.  If nobody would ever really need to install both at the
> same time, CONFLICTS is better.
> 
> > >Compiler warnings:
> > >
> > >There are (a lot of) compiler warnings about unused variables. The 
> > >original port ('generator') does not show them, so I suppose the 
> > >responsible is who did the patch. Should I fix them?
> > 
> > 	You can try to fix them removing unused variables and sending patches
> > 	upstream (to the developers). I guess you could use :
> > 	CFLAGS += -Wno-unused too.
> 
> The point about sending the patches to the original authors cannot be
> stressed too much.  If you *do* make a patch to a port, then there are
> two cases:
> - the patch applies to all systems, not just FreeBSD: in that case you
>   really ought to send it to the program developers, since it would
>   probably be useful to people using the program on other systems,
>   too;
> - the patch only applies to FreeBSD: make it so it detects whether it's
>   running on FreeBSD if possible (with C, that would usually be a matter
>   of an #ifdef __FreeBSD__; for Perl, if ($^O eq 'freebsd'); for shell
>   scripts, if [ "`uname -s`" = "FreeBSD" ], and so on).  If you can do
>   that, see the first case about sending it to the developers - it might
>   turn out to be useful for other systems, too.
> 
> In this particular case, CFLAGS += -Wno-unused looks like a good
> workaround, although it might fail if the port is compiled with a
> compiler other than GCC.  If you can take the time to actually fix the
> unused variable definitions, it would indeed be best to do so and send
> the patch to the authors.
> 
> > >Type decalrations:
> > >
> > >The modified version (generator-cbiere) did not compile because there was 
> > >an invalid type declaration "u_int64_t", that I changed into "uint64_t". 
> > >Then I noticed declarations saying "uint8", and I think the standard 
> > >defines it as "uint8_t". Should I change them?
> > 
> > 	Just do a patch, or use REINPLACE_CMD.
> 
> Careful there - if you use REINPLACE_CMD, you have to be *certain* that
> you will only replace the literal string 'uint8' when it is NOT part of
> a correct 'uint8_t' declaration :)
> 
> > >Patching:
> > >
> > >In almost all the cases I will end with more than one patch, so: should I 
> > >use different patches or merge them in one?
> > 
> > 	Try to create a patch for each file modified and name it like these :
> > 	x patch-src::Makefile.in if the patch modifies
> > 	${WRKDIR}/src/Makefile.in.
> > 	x patch-foo.c if the patch modifies ${WRKDIR}/foo.c.
> > 
> > 	Put these patches in ${FILESDIR} (files/).
> 
> This is generally regarded as the correct way to do things - usually.
> However, if there are dozens (or in some cases even hundreds) of files
> to be patched for a single purpose (e.g. changing #include <malloc.h> to
> #include <stdlib.h>, or adding an #include <sys/types.h> to many files
> as needed, or something), then it might be a better idea to combine
> *those fixes* in a single patchfile.  However, in that case, try to
> avoid patching the same source file in two different patchfiles, as
> explained in the Porter's Handbook.  For any 'should I...' or 'how do
> I...' questions related to ports, please try the Porter's Handbook first
> :)
> 
> G'luck,
> Peter
> 
> -- 
> Peter Pentchev	roam at ringlet.net    roam at cnsys.bg    roam at FreeBSD.org
> PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
> Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
> If the meanings of 'true' and 'false' were switched, then this sentence wouldn't be false.
> 

Thanks to all for your replies.

About the distribution, I did the following (it is right?):
DISTNAME=       generator-0.35-cbiere
EXTRACT_SUFX=   .tar.bz2
WRKSRC=		${WRKDIR}/generator-0.35-cbiere
MASTER_SITES=   http://www.ghostwhitecrab.com/generator/
USE_BZIP2=      yes

Installation:
The two ports will not be needed at the same time but I changed the binary name (was that right?). In case that is not good practice, how can I tell the other port's maintainer to add a CONFLICTS line (send PR, mail, etc.)?

Compiler warnings:
I tried to fix them, but the warnings are in 15 files generated by another C source file that is compiled and run to generate these files (it uses a kind of template for the functions, so it uses the same variables, but initialized with different values).
The original port did not show the warnings because the options "-Wall" and "-Wunused" were disabled (inside the real port's structure). So I used reinplace to disable them from 'configure.ac' and then added 'USE_AUTOCONF_VER=259'.

Data types:
Almost every file uses the format "[us]intXX" (int8, uint8, sint16). How can I implement a Perl script (I mean, I already made it) to process all source and header files (.h, .c) and add "#include <stdint.h>". Only for curiosity: I know the standard data types use the format "[u]intXX_t" and are decalred in "stdint.h". But where are the other types declared? Are them standard?

Patches:
At this point I end up with only one patch (main/generator.c: u_int64_t > uint64_t).

Today I was compiling the port and the file (at the author's website) changed. So I had to do a 'make makesum' again. If I submit the port, will I have to update it each time the md5 sum changes?

So my port (for now) is as follows, I appreciate any suggestions and/or comments. There are some notes at the end.

----------BEGIN----------
PORTNAME=	generator-cbiere
PORTVERSION=	0.35
PORTREVISION=	0
CATEGORIES=	emulators
DISTNAME=	generator-0.35-cbiere
EXTRACT_SUFX=	.tar.bz2
MASTER_SITES=	http://www.ghostwhitecrab.com/generator/
WRKSRC=		${WRKDIR}/generator-0.35-cbiere

MAINTAINER=	alejandro at varnet.biz
COMMENT=	SEGA Genesis emulator

LIB_DEPENDS=	jpeg.9:${PORTSDIR}/graphics/jpeg

PLIST_FILES=	bin/generator-cbiere-gtk
USE_BZIP2=	yes
USE_GNOME=	gtk12
USE_SDL=	sdl
USE_REINPLACE=	yes
USE_GMAKE=	yes
GNU_CONFIGURE=	yes
USE_AUTOCONF_VER=	259
CONFIGURE_TARGET=	--build=${MACHINE_ARCH}-portbld-freebsd${OSREL}
CONFIGURE_ENV=	CPPFLAGS="-I${LOCALBASE}/include" \
		LDFLAGS="-L${LOCALBASE}/lib"
CONFIGURE_ARGS=	--with-gtk --with-sdl-audio
MAKE_ARGS=	ACLOCAL="${TRUE}" AUTOCONF="${TRUE}" AUTOMAKE="${TRUE}" \
		AUTOHEADER="${TRUE}"

.include <bsd.port.pre.mk>

.if ${ARCH} == "alpha" && ${OSVERSION} >= 502102
BROKEN=		"Does not configure on alpha 5.x"
.endif

.if ${ARCH} == "i386"
BUILD_DEPENDS+=	nasm:${PORTSDIR}/devel/nasm
CONFIGURE_ARGS+=	--with-raze
.else
CONFIGURE_ARGS+=	--with-cmz80
.endif

post-patch:
	@${REINPLACE_CMD} -e 's|-O3||g ; \
	 s|-minline-all-stringops||g ; \
		 s|-march=pentium||g ; \
		 s|-malign-loops=5||g ; \
		 s|-malign-jumps=5||g ; \
		 s|-malign-functions=5||g ; \
		 s|-Wall||g ; \
		 s|-Wunused||g ; \
		 s|-W\ ||g ; \
		 s|generator|generator-cbiere|g' ${WRKSRC}/configure.ac
	@${REINPLACE_CMD} -e 's|generator-|generator-cbiere-|g ; \
		 s|generator_|generator-cbiere_|g' \
		 ${WRKSRC}/main/Makefile.in

.include <bsd.port.post.mk>
----------END-----------

It is based on the port of the original 'generator' (I did not changed it too much).

The reinplace for main/Makefile.in changes some rules like 'generator-gtk' or 'generator-sdl' to 'generator-cbiere-gtk' and 'generator-cbiere-sdl'.

The original port uses '--with-gtk' (like this), but there are other ways to compile it, and will result in different binaries. Should I add allow the user to choose?

Thanks and Best Regards,
Ale