본문 바로가기

Experience

Ant를 이용한 AsDoc, SWC 컴파일 - Troubleshoot

Introduction

알고보면 너무 사소한데 원인을 알아내기 까지엔 너무 많은 시간이 걸리는것 같습니다. 너무 사소하기 때문에 너무 쉽게 잊어버리는 걸까요. 이렇게 정리라도 해두지 않으면 "이거 어떻게 했는데..." 하면서 다음에 또 같은 시행착오를 하게 되지요. Flash Builder에서 Ant task를 이용하여 AsDoc 문서화 및 배포용 SWC파일을 컴파일하는 과정에서, 잘 풀리지 않아 시간잡아 먹게한 몇가지에 대해 적어볼까 합니다.


Case 1 : AsDoc 관련

태그는 반드시 짝을 이루어 사용하는 것이 좋습니다.

<P>태그라 하더라도 반드시 </P>닫아줍니다. (<br> 예외)

태그는 소문자로 작성하는 것이 좋습니다.

asdoc에서 주석문내의 태그는 소문자로 작성하는 것이 좋습니다. 대문자로 작성한 경우 에러는 나지 않지만 출력이 되지 않는 경우도 종종 있습니다.

주석 줄바꿈 후 "*" 문자 다음에 공백을 유지합니다.

주석문에서 줄바꿈한 뒤 "*" 문자 다음에 공백없이 태그를 쓰는 경우 에러가 발생하는 태그가 있습니다.

예를 들어 "* <p>~</p>"구문은 정상 작동하나 "*<p>~</p>"는 에러가 나는 어처구니 없는 상황이 벌어집니다. 반드시 빈칸을 삽입하는게 좋습니다. 다음은 원인과 전혀 관련없는 내용으로 출력된 에러입니다. 쓴적이 없는 <test>태그 어쩌고 하는 내용 때문에 엉뚱하게 <test> 찾느라고 한참을 해멧습니다. 잘못된 에러 메세지가 더 힘들게 하는군요. 

[exec] [Fatal Error] :15:15: 요소 유형 "test"은(는) 일치하는 끝 태그 "</test>"(으)로 종료해야 합니다.
[exec] 올바르지 않은 형식의 텍스트입니다. 자세한 내용은 D:\SVN\vulcan project update\trunk\src\vulcan_project_release\release_build\asDoc\validation_errors.log을(를) 참조하십시오.

클래스 정의를 찾을 수 없습니다.

구문 체크시 클래스 참조를 할 수 없 을때 에러가 발생 합니다. Flash Builder의 컴파일 체크에서는 에러가 발생하지 않는데도 asdoc에서 이런 에러가 발생 한다면 보통 MXML에서 인라인으로 작성된 클래스의 경로를 찾지 못해서 발생했을 수 있습니다. 이전 포스팅에서 설명한것 처럼 라이브러리 경로 또는 소스 경로를 asdoc 파라메터로 추가해 줍니다.

[exec] D:\SVN\vulcan project update\trunk\src\com.vulcan.application.navigator\src\com\vulcan\application\navigator\tab\skins\TabNavigatorSkin.mxml(106): 오류: 정의되지 않은 속성 ViewStackRenderer(com.vulcan.application.navigator.stack 패키지)에 액세스했습니다.
[exec] <stack:SkinnableViewStack id="viewStack"
[exec] D:\SVN\vulcan project update\trunk\src\com.vulcan.application.navigator\src\com\vulcan\application\navigator\tab\skins\TabNavigatorSkin.mxml(106): 오류: com.vulcan.application.navigator.stack:ViewStackRenderer 정의를 찾을 수 없습니다.

이 오류에 해결 방법은 command-line에서 실행하는 경우 asdoc.exe의 인자에 설정을 추가합니다.


Case 2 : Asset 관련

Asset 경로에 대한 오류

보통 외부 파일을 프로젝트에 Asset으로 포함시킬때 Embed 구문을 사용합니다. 그리고 이 구문에는 파일의 위치가 들어가게 됩니다. 절대 경로를 사용하면 항상 일정한 참조가 이루어 지므로 프로젝트 디렉토리를 변경하지 않는 이상 문제가 없겠지만 보통 이렇게 사용하지는 않죠.

반대로 상대경로를 사용할때는 프로젝트 디렉토리를 여기 저기 끌고다닐 수가 있지만 기준이 되는 Root (Base) Path가 변경될 때 역시 골치아픈 문제가 생깁니다. 저 역시 보통 상대 경로로 설정하는 편입니다만 이번 같이 프로젝트 외부에서 asdoc에 의해 참조가 요청이 되다보니 상대경로의 기준이 되는 root가 바뀌게 되어 좀 고생했습니다.

실제로 예를 들어 보겠습니다.

Asset을 포함하는 구문

<s:BitmapImage source="@Embed('./assets/dock/container/navigator/skins/popup_up.png')"></s:BitmapImage>

다음과 같이 Asset을 같은 디렉토리에서 관리함으로써(보통 skin파일과 같은 디렉토리) 경로 설정을 다음과 같이 한다.

<s:BitmapImage source="@Embed('popup_up.png')"></s:BitmapImage>

Flash Builder의 Package Explorer에서 Asset을 삭제할 때 주의해야 합니다.

Package Explorer에서 여러 Asset을 삭제할 때 한꺼번에 드래그해서 이동시키거나 삭제하지 않도록 합니다. 다음에러가 발생할 수도 있습니다. Asset이 삭제되었는데도 다음과 같이 파일을 찾지 못한다는 (계속 참조하는) 에러가 발생한다면 원상태로 되돌린 후 매번 Flash Builder가 갱신되었음을 확인하면서 하나씩 삭제합니다.(Flash Builder 버그인듯)


Case 3 : Flash Builder 문자 인코딩

저는 보통 Flash Builder의 인코딩을 UTF-8로 세팅해 놓고 사용합니다. 이 때문에 Ant에서 asdoc을 실행 했을때 message에 한글이 포함된 경우 다음과 같이 문자열이 깨지거나 아예 출력이 되지 않는 경우가 생깁니다. 로그파일 Console창 모두 한글이 깨져서 출력됩니다.

원래 asdoc은 다음과 같이 한글이 정상적으로 출력됩니다. 오류 내용을 알아야 고치든지 하겠지요. 삽질꽤나 했습니다. 인코딩 때문에 발생된 문제는 원인 찾기가 정말 힘든것 같습니다.

문제는 Flash Builder의 인코딩 설정 때문이었습니다. 다음과 같이 default로 설정하니 해결되었습니다. 설정하는 곳은 [Window > Preferences] 메뉴 에서 뜨는 Preferences 창에서 왼쪽 Tree 메뉴의 [General > Workspace] 입니다.