Writing Perl Modules for CPAN SAM'IREGAR APress Media, LLC Writing PerI Modules for CPAN Copyright ©2002 by Sam Tregar Origina1ly published by Apress in 2002 AH rights reserved. No part ofthis woIk may be reproduced or transmitted in any fonn or by any means, electronic or mechanica1, including photocopying, recording, or by any infonnation storage or retrieva1 system, without the priorwritten pennission ofthe copyright owner and the publisher. ISBN 978-1-59059-018-8 ISBN 978-1-4302-1152-5 (eBook) DOI 10.1007/978-1-4302-1152-5 Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement ofthe trademark. Technical Reviewers: Tesse Erlbaum and Neil Watkiss Editorial Directors: Dan Appleman, Gary Cornell, Tason Gilmore, Simon Hayes, Karen Watterson, Tohn Zukowski Managing Editor and Production Editor: Grace Wong Project Managers: Erin Mulligan, Alexa Stuart Copy Editor: Ami Knox Proofreader: Brendan Sanchez Compositor: Susan Glinert Indexer: Valerie Perry Caver Designer: Kurt Krames Manufacturing Manager: Tom Debolski Marketing Manager: Stephanie Rodriguez The infonnation in this book is distributed on an "as is" basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author nor Apress shall have any liability to any person or entity with respect to any 10ss or damage caused or alleged to be caused directly or indirectly by the infonnation contained in this work. In memory ofLuke and to Kristen who introduced us Contents at a Glance About the Author ................................................................................................. xi About the Technical Reviewers ................................................................ xiii Acknowledgments ...................................................................................................xv Introduction .................... ~ ................................................................................. xvii Chapter 1 CPAN ............................................................................................... 1 Chapter 2 Per1 Module Basics ............................................................... 21 Chapter 3 Module Design and Implementation ................................ 65 Chapter 4 CPAN Module Distributions ............................................... 95 Chapter 5 Submitting Your Module to CPAN ................................... 129 Chapter 6 Module Maintenance ............................................................. 139 Chapter 7 Great CPAN Modules ............................................................. 165 Chapter 8 PrograRITiing Per1 in C ...................................................... 175 Chapter 9 Writing C Modules with XS ............................................. 205 Chapter 10 Writing C Modules with Inline: :C .............................. 237 Chapter 11 CGI Application Modules for CPAN .............................. 253 Index ...................................................................................................................... 273 V Contents About the Author .......................................................................................... xi About the Technical Reviewers .................................................... xiii Acknowledgments ............................................................................................. xv Introduction ................................................................................................. xvii What You Need to Know .................................................................................... xxi System Requirements ....................................................................................... xxii Per1 Version ...................................................................................................... xxii Chapter 1. CPAN ............................................................................................. 1 Why Contribute to CPAN? .................................................................................. 1 Netlit/Ork Topology .................................................................................................. 3 Browsing CPAN ......................................................................................................... 6 Searching CPAN .................................................................................................... 12 Installing CPAN Modules ................................................................................ 13 ActivePerl PPM .................................................................................................... 19 Bundles ................................................................................................................... 20 CPAN' s Future ...................................................................................................... 20 Sununary ................................................................................................................... 20 Chapter 2 Perl Module Basics ....................................................... 21 Using Modules ...................................................................................................... 22 Packages ................................................................................................................. 24 Modules ................................................................................................................... 27 Read the Fine Manuals ..................................................................................... 64 Summary ................................................................................................................... 64 vii Contents Chapter 3 Module Design and Implementation ................... 65 Check Your Slack ................................................................................................ 65 Size Matters ......................................................................................................... 66 Document First ..................................................................................................... 66 Interface Design ................................................................................................ 73 Summary .................................................................................................................... 94 Chapter 4 CPAN Module Distributions ..................................... 95 Module Installation .......................................................................................... 95 Always Begin with h2xs ................................................................................... 98 Exploring the Distribution ......................................................................... 112 Portability ......................................................................................................... 122 Choosing a License .......................................................................................... 126 Summary .................................................................................................................. 128 Chapter 5 Submitting Your Module to CPAN ...................... 129 Requesting Comments ........................................................................................ 129 Requesting a CPAN Author ID ...................................................................... 131 Registering Your Namespace ......................................................................... 132 Uploading Your Module Distribution ....................................................... 134 Post-Upload Processing ................................................................................. 137 Summary .................................................................................................................. 138 Chapter 6 Module Maintenance ..................................................... 139 Growing a User Community ............................................................................. 139 Managing the Source ........................................................................................ 142 Making Releases ................................................................................................. 161 Summary .................................................................................................................. 163 Chapter 7 Great CPAN Modules ..................................................... 165 Hhat Makes a Great CPAN Module? .............................................................. 165 CGI.pm .................................................................................................................... 166 OBI ........................................................................................................................... 168 Storable ................................................................................................................ 169 Net: :FTP ................................................................................................................ 170 LHP ........................................................................................................................... 171 XML : :SAX ...............................................................................................................