오픈소스 프로젝트를 이용해서 개발을 해보신 분들은 소스코드를 문서화한 레퍼런스 문서(또는 개발자 매뉴얼)을 참고해서 개발해 본 경험이 있을 것 같습니다. 개발자를 위한 이러한 문서는 기본적으로 프로젝트 빌드 방법, 주요 아키텍쳐 설명 등의 내용들을 담기도 하고 소스코드에서 정의한 변수나 구조체와 함수 같은 것들이 소스 파일을 직접 열어서 찾아보지 않아도 보기 좋게 정리하거나 변수나 함수 간의 관계를 정리해서 보여주기도 합니다.
다음과 같은 프로젝트의 문서를 예시로 참고해 볼 수 있겠네요.
- CGAL : https://doc.cgal.org/4.2/CGAL.CGAL/html/index.html
- Eigen : http://eigen.tuxfamily.org/dox/
- Xerces-C++ : http://xerces.apache.org/xerces-c/apiDocs-3/classes.html
공개 되어있는 코드를 한줄한줄 따라가보며 파악할 수도 있지만 프로젝트의 규모가 커지고, 코드의 복잡도가 증가할수록 개발자를 위한 문서는 중요해집니다. 왜냐하면 문서를 읽으면 소스코드를 훨씬 빠르게 파악할 수 있기 때문입니다. 이러한 문서 덕분에 다른 개발자가 조금 더 쉽게 내 프로젝트에 기여할 수 있게 된다면 내 프로젝트에 참여하고 기여해주는 사람들이 더 많아질 수 있는 좋은 선순환의 시작점이 될 수 있을 것입니다.
하지만 문서를 작성하는 것도 큰 비용입니다. 아무리 설계와 개발을 하면서 문서를 만들더라도 점점 덩치가 커지는 소스코드의 모든 변수와 함수를 문서화 하려고 한줄 두줄 옮겨 적어가는 것은 매우 비효율적이겠죠. 게다가 소스코드는 계속해서 바뀌기 때문에 최신화하는 비용도 만만치 않을것입니다.
그러면 조금 더 효율적으로 소스코드를 문서화 할 수 있는 방법은 무엇이 있을까요?
Doxygen - 소스코드 문서화 도구
소스코드를 문서화하기 위한 대표적인 도구로 Doxygen를 소개합니다. Doxygen은 코드를 기반으로 문서를 생성하여 작성되므로 비교적 최신 상태로 유지하기가 쉽습니다. 특히 문서와 코드를 상호 참조 할 수 있어 실제 코드를 쉽게 참조 할 수 있다는 장점이 있습니다.
아직 큐브리드에서는 공식적으로 소스코드 레퍼런스 메뉴얼을 지원하지는 않습니다. 공식 홈페이지에서 제공하는 유저 매뉴얼이 잘 설명되어 있긴 하지만, 오픈소스 프로젝트인 큐브리드의 소스코드를 읽어보고 기여해보고 싶은 개발자의 입장에서는 아쉬움이 큰 것이 사실입니다. 이 글에서 소개하는 도구를 시작으로, 이러한 문서를 만들어나가다보면 큐브리드 프로젝트에 무언가 기여해보고 싶어하는 개발자가 많아질 수 있을거라 기대합니다.
이제부터 큐브리드 소스코드를 기반으로 문서를 생성해보도록 하겠습니다.
|
다음 섹션부터 단계별로 진행할 명령어는 큐브리드의 빌드환경인 CentOS 7을 기준으로 작성하였습니다. 설치하는 도구는 다양한 운영체제를 지원하기 때문에 각 환경에 맞게 설치 후 명령어 도구로 진행하면 됩니다. |
문서를 생성 할 코드 가져오기
큐브리드의 소스코드는 github 저장소에서 관리되고 있습니다. 경로는 다음과 같습니다.
다음의 git clone 명령어로 github의 큐브리드 소스코드를 복사해오는 명령어를 실행합니다. 꼭 git을 사용해서 코드를 가져올 필요 없이, 소스코드가 준비된 폴더 안에서 따라해보셔도 됩니다.
yum -y install git git clone https://github.com/cubrid/cubrid cd cubrid
Doxygen 설치하기
다음으로 Doxygen을 설치해보도록 하겠습니다. Doxygen에서 변수와 함수의 관계 그래프를 그리기 위해 graphviz라는 도구도 함께 설치합니다. 다른 운영체제의 경우 http://www.doxygen.nl/download.html를 참조하시면 됩니다.
yum -y install doxygen graphviz
Doxyfile 생성하고 설정하기
Doxyfile은 Doxygen으로 생성할 문서에 대한 설정 파일입니다. 다음 명령어로 Doxyfile을 생성할 수 있습니다.
doxygen -g my_conf
이제 폴더 내에 my_conf라는 파일이 만들어진 것을 확인할 수 있습니다. my_conf 외에 다른 이름으로 지정하는 것도 가능합니다. 만들어진 파일 (my_conf)를 텍스트 에디터로 열어보면, 굉장히 복잡해 보이는 파일이 하나 생성된 것을 확인할 수 있습니다. 하지만 대부분 기본 값으로 채워져 있는 일종의 템플릿이고 주석에서 각 설정에 대해 자세히 설명되어 있는 것을 ㅂ 볼 수 있습니다. 따라서 모든 설정을 여기서 소개하긴 힘들어 몇 가지 주요한 설정을 소개하고 넘어가도록 하겠습니다.
이제부터 설명하는 설정을 한번 그대로 설정해보며 문서를 만들어보려고 합니다.
먼저 프로젝트 이름부터 설정해보겠습니다. 텍스트 에디터에서 PROJECT_NAME을 찾아 기본 값으로 "My Project"라고 설정되어 있는 부분을 원하는 이름을 입력합니다.
저는 "CUBRID DOC"으로 입력해 보겠습니다.
PROJECT_NAME = "CUBRID DOC"
다음으로 INPUT을 찾아 = 이후에 src/compat를 입력합니다. INPUT으로 입력할 파일 또는 폴더를 설정합니다. 큐브리드는 큰 프로젝트라 생성이 오래 걸리기 때문에 이 예제에서는 큐브리드의 src/compat 폴더 내의 소스 파일에 대해서만 생성하려고 합니다.
INPUT = src/compat
이제 어떻게 Doxyfile 문서를 수정하는지 조금씩 감이 오실 것 같습니다. 간단한 설명과 함께 계속 따라해보겠습니다.
# 입력하려는 파일의 확장자를 지정할 수 있습니다.
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++
# 문서가 생성될 경로를 지정합니다.
OUTPUT_DIRECTORY = build_doc
# HTML로 된 문서만을 생성합니다.
GENERATE_HTML = YES
GENERATE_LATEX = NO
# 소스코드의 모든 요소를 문서화 대상으로 합니다.
EXTRACT_ALL = YES
이제는 소스코드로부터 다음의 그림과 같은 Caller 그래프를 그리기 위한 설정입니다.
CALLER_GRAPH는 어떤 함수를 호출하는 다른 함수에 대한 관계를 그려주는 그래프입니다. 이 설정 외에도 CALLER_GRAPH와 같은 섹션에 있는 다른 설정들을 이용해서 여러가지 그래프를 그려 볼 수 있습니다.
CALLER_GRAPH = YES
위에서 설명한 설정 외에도 수 많은 설정이 있습니다. Doxyfile에서 모두 기본값으로 설정되어 있으니 나중에 자신의 프로젝트에 맞게 여러가지 설정을 바꾸어보며 테스트 해보시면 됩니다.
설정한 Doxyfile을 사용해서 소스코드 레퍼런스 문서 생성
이제 doxygen 명령으로 doxyfile에서 설정한대로 문서를 생성할 수 있습니다. 쉽게 다음 명령어로 생성해봅시다.
doxygen my_conf
명령어를 입력하면 Parsing ...과 Generating .... 으로 시작하는 로그를 보실 수 있습니다. 문서 생성 과정이 끝나면 OUTPUT_DIRECTORY에서 입력한 build_doc 폴더내의 html를 들어가보면 index.html 파일이 있습니다. 이 파일을 열어보면 다음 그림과 같은 화면을 볼 수 있습니다.
상단의 Classes을 눌러보면 소스코드에서 정의된 구조체 또는 클래스를 확인할 수 있습니다.
구조체의 이름을 눌러 들어가보면 (e.g. db_domain_info) 다른 구조체와의 관계 그래프도 표시하고 있는 것을 확인할 수 있습니다.
마찬가지로 상단의 Files 탭을 클릭하면 파일의 목록을 볼 수 있습니다.
파일 이름을 클릭해보면 다음과 같은 그림을 볼 수 있습니다. 이 파일이 어떤 다른 헤더를 include 하는지 그려주기도 하고 어떤 변수와 함수를 정의하고 있는지 문서화하여 보여줍니다.
마무리
여기까지 Doxygen을 이용해서 큐브리드 소스코드의 레퍼런스 문서를 만들어보았습니다. 간단히 Doxygen에 대해 소개하기 위한 목적으로 작성했기 때문에 이 강력한 도구를 충분히 설명하기엔 부족합니다. 이 글에서 Doxygen가 가진 기능을 모두 다루어보지는 못하였지만, Doxygen 매뉴얼을 참고하여 조금만 사용해보면 여러분이 지금 수행하고 있는 프로젝트의 소스코드를 문서화할 때 하나의 좋은 옵션이 될 수 있을 것으로 기대합니다.
마무리를 하려니 무언가 찝찝함이 남습니다. 서론에서 "소스코드는 계속해서 바뀌기 때문에 최신화하는 비용도 만만치 않다"고 언급했었습니다. 소스코드가 바뀔때마다 doxygen으로 생성하고, 생성된 문서를 배포하는 과정도 비용입니다. 이 부분에 대해서는 다음 글에서 Travis CI와 Github pages를 이용해서 최신화된 코드에 대해 Doxygen으로 문서를 배포하는 방법에 대해 소개할 예정입니다.
긴 글 읽어주셔서 감사합니다.
참고 자료
- Doxygen, http://www.doxygen.nl/
- Graphviz, http://www.graphviz.org/
CUBRID Network Diagram (CUBRID Version 9.3, 10.1)
