본문 바로가기

Experience

Ant를 이용한 AsDoc, SWC 컴파일

Introduction

Flex SDK에 포함되어 있는 ASDoc 문서화 tool을 이용하여 어플리케이션의 클래스에 작성한 일정 형식의 주석로부터 API 언어의 레퍼런스 문서를 HTML로 일괄적으로 작성할 수 있습니다. Vulcan Project에서도 역시 ASDoc 툴을 사용해 「Vulcan Project Reference」를 작성합니다.

보통 AsDoc 툴은 command-line에서 직접 사용하거나 Ant를 이용하여 Build하는 방법으로 많이 사용하는 것 같습니다. Adobe 도움말 리소스 센터라든지 여러 블로그에서 그 사용법을 자세하게 알려주고 있습니다. 다음은 AsDoc을 통해 Vulcan Project를 문서화하는 방법과 어려웠던점 몇가지를 정리해 보았습니다.

여러 프로젝트의 문서를 통합

큰 프로젝트는 보통 기능을 세분화 시켜 개별적인 여러 프로젝트들로 나누어 진행을 하게 됩니다. 이런 작은 단위의 프로젝트들이 모여 하나의 프로젝트가 완성되었을때 해당 문서도 통합해서 배포해야할 필요가 있습니다. 이런경우 여러 단위 프로젝트 문서를 일괄적으로 생성하고 배포하기 위해 제가 사용한 방법입니다.

Vulcan Project는 위와 같이 여러개의 라이브러리 프로젝트로 구성되어 있습니다. 이 프로젝트들을 모두 하나의 폴더에 문서화 시키겠습니다.


Step1 : Release 관리 프로젝트 생성

위 그림에서 마지막에 보이는 vulcan_project_release라는 프로젝트가 Release 문서를 생성하기 위해 만든 프로젝트 입니다. 내부에는 아무런 클래스도 없는 비어있는 프로젝트 입니다. 단지 Flash Builder에서 지원하는 Ant를 이용하여 배포용 SWC와 문서를 생성하기 위한 공간입니다.

release_build 디렉토리에 배포용 swc와 문서를 생성할 것입니다.


Step2 : Ant Build 파일 작성

Flash Builder에서는 Ant를 기본적으로 지원합니다. Flex Builder를 사용하더라도 간단한 플러그인 설치로 사용 가능합니다. Ant에 대해서 전혀 모르더라도 XML만 읽을 수 있으면 쉽게 사용할 수 있습니다.

build.ant와 build.properties 파일을 작성합니다. build.ant는 xml기반으로 파일생성, 삭제, 실행등의 작업내용을 정의하는 일종의 배치파일과 같습니다. build.properties파일은 build.ant 파일에서 사용하는 여러 속성값 또는 상수 값들을 관리하기 쉽게 따로 떼어내어 기록한 파일입니다. 따라서 build.ant의 헤더에는 build.properties파일을 참조한다는 구문이 들어야 할 겁니다.

인터넷에서 수집한 여러 자료들을 기초로 해서 저는 다음과 같이 작성했습니다.

build.properties

build.ant에서 쓰이는 속성값을 정의합니다.

build.ant

<target> 태그에 작업 내용을 기술합니다.

아직 프로젝트들을 추가하지 않은 가장 기초적인 상태입니다. 간단하게 <target> 태그를 읽어 보자면

01.SWC Build :
  • clean_swc <target>을 먼저 실행한 후 compc.exe 속성값에 해당하는 프로그램을 실행 시킵니다. 전달되는 인자는 arg 노드의 line 속성의 내용으로 command-line에서 parameter를 설정하는 syntax로 기술합니다.
02.AsDoc Build :
  • clean_asdoc, 04.Record Log File <target>을 순차적으로 실행 시킨 후 asdoc.exe 속성값에 해당하는 프로그램을 실행 시킵니다. 전달되는 인자는 마찬가지로 asdoc을 command-line으로 실행시킬 때 구문을 arg 노드의 line 속성에 기술 하였습니다.
03.help :
  • 간단하게 "asdoc -help" 입니다.
04.Record Log File :
  • 출력되는 내용을 asdoc.logfile 속성값에 해당하는 파일에 기록합니다.

대충 이런 패턴입니다.


Step3 : 프로젝트 추가

build.ant 파일을 수정하여 문서화 하고자 하는 프로젝트를 추가하도록 하겠습니다.

SWC 컴파일의 경우

각각의 프로젝트의 swc 파일을 라이브러리 경로에 추가했습니다. 따라서 컴파일 작업시에 각각의 swc 내용도 함께 컴파일 됩니다. -include-libraries에 대한 설명은 FLex SDK 도움말의 compc 컴파일러 parameter를 참고하시기 바랍니다.

AsDoc 문서 생성의 경우

-doc-sources에 프로젝트들이 추가되었습니다. -source-path를 지정한 이유는 asdoc.exe에서 구문 분석할때 skinClass 속성이나 itemRenderer 속성같이 MXML 파일의 attribute에 작성된 Class는 찾지 못하고 에러를 발생시킵니다. 따라서 -source-path 또는 -library-path 둘중 한가지 방법으로 소스 참조를 가능하도록 해주어야 합니다.

-source-path 와 -library-path parameter는 Poperties 팝업창에서 Flex library Build Path 항목의 Source Path, Library Path 탭에서 설정하는 내용과 같은 역할을 합니다. 엄밀히 말하자면 이 옵션은 asdoc이 아닌 compc 컴파일러의 parameter에 해당합니다. parameter에 대한 설명은 FLex SDK 도움말의 asdoc을 참고하시기 바랍니다.


Step4 : Ant Build

Flash Builder의 Ant 속성창에서(안보인다면 메뉴에서 Window > Show View > other > Ant에서 Ant 선택) 우상단의 개미+ 아이콘을 클릭하여 방금 작성한 buid.ant 파일을 등록합니다. 아래 그림과 같이 각 <target>의 이름이 나타납니다.

각각의 <target>을 더블클릭하여 개별적으로 실행시킬 수도 있고, 가장 큰 제목을 더블클릭하여 default로 지정된 <target>을 실행시킬 수도 있습니다. 실행 도중 출력되는 메세지나 에러 메세지는 Console창에 나타납니다.


Troubleshoot

asdoc 툴은 클래스의 주석문 내의 태그 뿐만 아니라 Class에 대해서도 상당히 엄격한 구문 체크를 합니다. 많은 양의 오류 내용은 console창에서 확인할 수도 있지만 위와같이 로그 파일로도 작성되게 할 수도 있고, 오류가 생겼을 때에만 asdoc에서 자체로 생성하는 결과물 디렉토리의 validation_errors.log 파일에서도 확인할 수 있습니다.

AsDoc 문서화 작업을 진행하면서 내공이 달렸는지 몇번의 삽질이 있었습니다. 저의 경우에만 국한되게 특별히 발생된 내용일 수도 있고 아주 간단한 내용일 수도 있지만 같은 삽질 두번하면 명줄 짧아지기 때문에 간단히 정리해 봅니다.