Perl/Dist-Zilla

• http://dzil.org/
  • IE에선 잘 안 열리던데 튜토리얼 페이지로 바로 가려면 http://dzil.org/tutorial/start.html
• Dist::Zilla

1. 전역 설정

2. 새 프로젝트 생성

3. 모듈 만들기

4. 테스트

5. 빌드

6. 플러그인들

6.1. 번들 필터링

6.2. 메타 정보 추가

6.3. 의존성 명시

6.4. POD 보강

6.5. 버전 넘버 관리

6.6. 추가 파일 생성

7. 프로파일 설정

8. CPAN에 업로드

8.1. 계정 만들기

8.2. 모듈 이름 짓기

8.3. 업로드

8.4. 자잘한 것들

9. 단점과 대안

10. 참고

11. Comments

1. 전역 설정

• 관련 튜토리얼: http://dzil.org/tutorial/new-dist.html , http://dzil.org/tutorial/initial-setup.html

[%User]
name  = ****
email = ****

[%Rights]
license_class    = Perl_5
copyright_holder = ****

2. 새 프로젝트 생성

• 관련 튜토리얼: http://dzil.org/tutorial/new-dist.html

[gypark@www temp]$ dzil new App::gitfancy
[DZ] making target dir /home/gypark/temp/App-gitfancy
[DZ] writing files to /home/gypark/temp/App-gitfancy
[DZ] dist minted in ./App-gitfancy
[gypark@www temp]$ cd App-gitfancy/
[gypark@www App-gitfancy]$ tree
.
|-- dist.ini
`-- lib
    `-- App
        `-- gitfancy.pm

2 directories, 2 files

name    = App-gitfancy
author  = **** <****>
license = Perl_5
copyright_holder = ****
copyright_year   = 2012

version = 0.001

[@Basic]

• "@"로 시작하는 플러그인 번들들은 Dist::Zilla::PluginBundle::Basic 와 같은 형태로 모듈 이름이 구성된다.
• [NextRelease] 등 "@" 없이 적힌 플러그인들은 Dist::Zilla::Plugin::NextRelease 와 같은 형태로 모듈 이름이 구성된다.

3. 모듈 만들기

package App::gitfancy;
use strict;
use warnings;
# ABSTRACT: shows `git log` with a more readable graph

1;

#!/usr/bin/perl
use strict;
use warnings;

# ABSTRACT: shows `git log` with a more readable graph
# PODNAME: git-fancy

use autodie;
use Getopt::Long;
use Pod::Usage;
...
=pod

=head1 SYNOPSIS

    git-fancy [options] [-- arguments for git-log]
...
=cut

4. 테스트

• 관련 튜토리알: http://dzil.org/tutorial/testing.html

use Test::More tests => 1;

BEGIN {
    use_ok( 'App::gitfancy' ) or print "Bail out!\n";
}

[gypark@www App-gitfancy]$ dzil test
[DZ] building test distribution under .build/jtHOrgJut1
[DZ] beginning to build App-gitfancy
[DZ] guessing dist's main_module is lib/App/gitfancy.pm
[DZ] extracting distribution abstract from lib/App/gitfancy.pm
[DZ] writing App-gitfancy in .build/jtHOrgJut1
Checking if your kit is complete...
Looks good
Writing Makefile for App::gitfancy
Writing MYMETA.yml and MYMETA.json
cp lib/App/gitfancy.pm blib/lib/App/gitfancy.pm
cp bin/git-fancy blib/script/git-fancy
/home/gypark/perl5/perlbrew/perls/perl-5.14.2/bin/perl -MExtUtils::MY -e 'MY->fixin(shift)' -- blib/script/git-fancy
Manifying blib/man1/git-fancy.1
Manifying blib/man3/App::gitfancy.3
PERL_DL_NONLAZY=1 /home/gypark/perl5/perlbrew/perls/perl-5.14.2/bin/perl
"-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t .. ok
All tests successful.
Files=1, Tests=1,  0 wallclock secs ( 0.02 usr  0.01 sys +  0.02 cusr  0.00 csys =  0.05 CPU)
Result: PASS
[DZ] all's well; removing .build/jtHOrgJut1

5. 빌드

• 관련 튜토리얼: http://dzil.org/tutorial/how-build-works.html

[gypark@www App-gitfancy]$ dzil build
[DZ] beginning to build App-gitfancy
[DZ] guessing dist's main_module is lib/App/gitfancy.pm
[DZ] extracting distribution abstract from lib/App/gitfancy.pm
[DZ] writing App-gitfancy in App-gitfancy-0.001
[DZ] building archive with Archive::Tar; install Archive::Tar::Wrapper for improved speed
[DZ] writing archive to App-gitfancy-0.001.tar.gz

[gypark@www App-gitfancy]$ ls
App-gitfancy-0.001/  App-gitfancy-0.001.tar.gz  bin/  dist.ini  lib/  t/

[gypark@www App-gitfancy]$ tree App-gitfancy-0.001
App-gitfancy-0.001
|-- LICENSE
|-- MANIFEST
|-- META.yml
|-- Makefile.PL
|-- README
|-- bin
|   `-- git-fancy
|-- dist.ini
|-- lib
|   `-- App
|       `-- gitfancy.pm
`-- t
    `-- 00-load.t

4 directories, 9 files

perl Makefile.PL
make
make test
make install

6. 플러그인들

6.1. 번들 필터링

;[@Basic]
[@Filter]
-bundle = @Basic
-remove = UploadToCPAN

[FakeRelease]

• Dist::Zilla::PluginBundle::Filter

@Basic 번들을 사용하면서, 그 번들에 포함된 UploadToCPAN 플러그인만 제거한다. dzil release할 때 CPAN에 업로드하는 일이 없도록 하여 실수로 업로드하는 것을 막음

• Dist::Zilla::Plugin::FakeRelease

dzil release할 때 CPAN에 업로드하는 시점에, 아무 일도 하지 않고 로그만 출력한다.

6.2. 메타 정보 추가

[MetaResources]
;homepage       =
;bugtracker.web =
repository.web = http://github.com/gypark/App-gitfancy
repository.url = git://github.com/gypark/App-gitfancy.git
repository.type = git

• Dist::Zilla::Plugin::MetaResources

위에 적은 항목들을 META.yml에 추가해준다.

위 경우는 다음과 같이 추가되었음

resources:
  repository: git://github.com/gypark/App-gitfancy.git

6.3. 의존성 명시

• 관련 튜토리알: http://dzil.org/tutorial/prereq.html

[AutoPrereqs]
[Prereqs / RuntimeRequires]
Moose = 0

• Dist::Zilla::Plugin::AutoPrereqs

소스 코드의 use, require, base 등의 키워드를 검색하여 자동으로 필요한 모듈을 찾아준다.

• Dist::Zilla::Plugin::Prereqs

여기에서는 명시적으로 필요한 모듈을 적어준다. = 숫자는 최소 버전. 여기서는 Runtime에만 필요하다고 추가로 적어주고 있음

6.4. POD 보강

• 관련 튜토리알: http://dzil.org/tutorial/writing-docs.html

[PodWeaver]

• Dist::Zilla::Plugin::PodWeaver

모듈 작성자가 POD내용에 관한 부분만 적으면, 이 플러그인이 POD 형식에 맞춰 헤딩이나 리스트 등의 문법을 작성해준다. 그런데 나도 정확히 쓰는 법은 잘 모르겠고, 위에서 봤듯이 # ABSTRACT: 뒤에 적은 내용이 자동으로 NAME 항목으로 변환된다.

;[PodCoverageTests]
[PodSyntaxTests]

• Dist::Zilla::Plugin::PodCoverageTests
• Dist::Zilla::Plugin::PodSyntaxTests

위 두 플러그인은 dzil release하는 시점에 POD가 제대로 작성되었는지를 테스트해 준다.

6.5. 버전 넘버 관리

• 관련 튜토리알: http://dzil.org/tutorial/versioning.html

• 앞서 봤던 기본 설정에서는 dist.ini에 version = 버전번호 형태로 직접 적어준다.
• 메인 모듈에 our $VERSION = 버전번호; 구문을 적고, Dist::Zilla::Plugin::VersionFromModule 플러그인을 사용하면 그 버전 값을 읽어와서 사용한다.
• Dist::Zilla::Plugin::AutoVersion 플러그인을 사용하면 현재 날짜에 기반 또는 작성자가 지정한 형태에 맞춰 자동으로 버전을 적어준다.
• Git 등을 사용할 경우 git 저장소의 태그를 보고 현재 버전값을 추출한다.

[PkgVersion]
[NextRelease]
[Git::NextVersion]

• Dist::Zilla::Plugin::PkgVersion

이 플러그인은 VersionFromModule의 역이랄까, dzil이 설정한 현재 버전 값을 모듈 파일에 자동으로 삽입한다:

{
   $MyModule::VERSION = 0.001;
}

• Dist::Zilla::Plugin::NextRelease

Changes 파일에 {{$NEXT}}라고 적어 두면, 이 자리에 현재 버전 번호를 치환해 넣는다

현재 버전의 수정 내용은 {{$NEXT}} 아래에 적어두면 된다.

build 할 때는 Changes 파일에 이번의 버전 번호와 날짜 시각을 치환해서 배포용 파일을 만든다.

release 가 끝나면 그렇게 수정한 Changes 파일의 내용을 작업 디렉토리의 Changes 파일에 반영한다.

• Dist::Zilla::Plugin::Git::NextVersion

이것이 현재 버전 번호를 설정하는 플러그인인데, git tag 목록을 뽑고, ^v(.+)$ 정규식에 매치되는 태그를 찾아서 그 중 제일 마지막 번호를 추출한 후, 그 숫자를 1증가시켜서 현재 버전으로 설정한다. 예를 들어 v0.002 라는 태그가 있다면 dzil build를 수행하면 현재 버전은 0.003으로 처리된다.

6.6. 추가 파일 생성

;[ReadmeMarkdownFromPod]
[InstallGuide]

• Dist::Zilla::Plugin::InstallGuilde

빌드할 때 모듈의 설치방법이 적힌 INSTALL 문서를 생성한다.

7. 프로파일 설정

• 관련 튜토리알: http://dzil.org/tutorial/minting-profile.html

$ cd ~/.dzil/profiles/standard/
$ tree
.
|-- Module.pm
|-- plugins.ini
|-- profile.ini
`-- skel
    |-- Changes
    `-- weaver.ini

1 directory, 5 files

• profile.ini 는 이 프로파일 자체의 설정이 담긴다.

[DistINI]
append_file = plugins.ini

[GatherDir::Template]
root             = skel
include_dotfiles = 1

[TemplateModule / :DefaultModuleMaker]
template = Module.pm

• 모듈 작성 디렉토리의 dist.ini 파일에는 plugins.ini의 내용을 뒤에 덧붙이고
• skel 디렉토리 내에 있는 파일들을 기본적으로 모듈 작성 디렉토리에 복사하고
• Module.pm 파일을 메인 모듈의 템플릿으로 사용한다.

• plugins.ini 파일에 적어 둔 내용은, dist.ini의 이름과 저작권 등의 기본 정보 아래에 복사된다. 앞서 봤던 플러그인 이름과 설정들을 그대로 적어주면 되겠다.

• Module.pm 파일의 내용이, 생성되는 메인 모듈의 처음 내용이 된다. {{$name}} 부분이 실제 모듈 이름으로 치환된다.

package {{$name}};
# ABSTRACT: ...

use Moose;
...

• skel 디렉토리 안에는 .gitignore, Changes, 그리고 PodWeaver 플러그인에서 사용하는 설정 파일인 weaver.ini 가 들어 있다. Changes의 경우는 다음과 같다:

Release history for {{ $dist->name }}

{{ '{{ $NEXT }}' }}
    First version, released on unsuspecting world.

이것은 dzil new 했을 때 이렇게 바뀌어 적용되고:

Release history for App-gitfancy

{{ $NEXT }}
    First version, released on unsuspecting world.

여기서 다시 {{ $NEXT }} 부분은 위에서 얘기한 버전 관리 플러그인이 빌드 시점에 치환한다.

8. CPAN에 업로드

8.1. 계정 만들기

• dzil 튜토리알: http://dzil.org/tutorial/release.html
• dzil 튜토리알: http://dzil.org/tutorial/cpan-dists.html
• [CPAN FAQ의 "How do I contribute modules to CPAN?"]
• http://www.cpan.org/modules/04pause.html - PAUSE

8.2. 모듈 이름 짓기

8.3. 업로드

8.4. 자잘한 것들

9. 단점과 대안

• Dist::Milla - Dist::Zilla의 플러그인 번들이면서 따로 커맨드를 제공
• Minilla - 아예 새롭게, 같은 일을 하는 경량 플랫폼을 만들려고 하는 듯

• Dist::Zilla::Plugin::PathInRoot

10. 참고

• http://dinomite.net/2011/creating-a-perl-module-in-modern-style/

• http://www.slideshare.net/rjbs/distzilla-maximum-overkill-for-cpan-distributions - 슬라이드
• http://www.perl.com/pub/2010/03/more-code-less-cruft-managing-distributions-with-distzilla.html - 기존에 개발하던 모듈 배포본을 dzil 기반으로 옮기는 얘기
• http://blog.fox.geek.nz/2011/01/making-minting-profile-as-cpanized-dist.html - 프로파일 관련
• http://f00li5h.pin21.com/blog/dzil:-a-casual-walkthrough-of-Dist::Zilla.html
• http://d.hatena.ne.jp/k-z-h/20100523/p1

11. Comments

각주:
1. https://metacpan.org/source/TOKUHIROM/App-cpanoutdated-0.20/bin/cpan-outdated
2. https://metacpan.org/source/TOKUHIROM/App-cpanoutdated-0.20/lib/App/cpanoutdated.pm
3. POD를 포함한 전체 코드는 https://github.com/gypark/App-gitfancy/blob/master/lib/App/gitfancy.pm
4. https://github.com/gypark/App-gitfancy/blob/master/bin/git-fancy
5. keedi님께 많은 도움 받았음. 감사합니다.
6. keedi님에게 통채로 받았음. 감사합니다.
7. 아시는 분 가르쳐주세요~