跳轉到內容

ROSE 編譯器框架/如何新增一個新的專案目錄

Add links
來自華夏公益教科書，自由的教科書


大多數建立在 ROSE 庫之上的程式碼開發，其最初都是作為 projects 目錄中的專案開始的。一些專案在成熟後最終被重構到 ROSE 庫中。本章介紹如何在 ROSE 中新增新的專案。

方法 1：新增新專案的新方法

[編輯 | 編輯原始碼]

Robb Matzke 在 ROSE 中添加了一個新功能，可以更輕鬆地將新專案新增到 ROSE/projects 中。

  • 建立一個 $ROSE/projects/whatever 目錄。
  • 在該目錄中，建立一個名為“rose.config”的檔案。
  • 在該檔案中，新增一行 AC_CONFIG_FILES(projects/whatever/Makefile)

透過執行 ./build 將更新 rose/config/support-projects.m4。

您仍然需要有自己的 Makefile.am。最簡單的示例是

方法 2：必需檔案

[編輯 | 編輯原始碼]

ROSE 專案封裝了使用 ROSE 庫的完整程式或一組相關程式。每個專案都作為 ROSE “projects”目錄的子目錄存在，並且應包含檔案“README”、“config/support-rose.m4”、“Makefile.am”以及任何必需的原始檔、指令碼、測試等。

  • “README”應提供關於專案目的、演算法、設計、實現等的解釋。
  • “support-rose.m4”將專案整合到 ROSE 構建系統中，以一種允許專案成為可選元件的方式（它們可以被停用、重新命名、刪除或從分發中移除，而無需更改任何 ROSE 配置檔案）。大多數舊專案都缺少此檔案，因此與構建系統耦合得更緊密。
  • “Makefile.am”用作 ROSE 使用的 GNU automake 系統的輸入，以生成 Makefiles。
  • 每個專案還應包含所有必需的原始檔、文件和測試用例。

設定 support-rose.m4

[編輯 | 編輯原始碼]

“config/support-rose.m4”檔案將專案整合到 ROSE 配置和構建系統中。至少，它應該包含對 autoconf AC_CONFIG_FILES 宏的呼叫，其中包含專案的 Makefiles（不帶“.am”副檔名）和它的 doxygen 配置檔案（不帶“.in”副檔名）的列表。它還可以包含任何其他必要的 autoconf 檢查，這些檢查尚未由 ROSE 的主配置指令碼執行，包括根據專案先決條件的可用性來啟用/停用專案的程式碼。

這是一個示例

dnl List of all makefiles and autoconf-generated                          -*- autoconf -*-
dnl files for this project
AC_CONFIG_FILES([projects/DemoProject/Makefile
                 projects/DemoProject/gui/Makefile
                 projects/DemoProject/doxygen/doxygen.conf
                ])

dnl Even if this project is present in ROSE's "projects" directory, we might not have the
dnl prerequisites to compile this project.  Enable the project's makefiles by using the
dnl ROSE_ENABLE_projectname automake conditional.  Many prerequisites have probably already
dnl been tested by ROSE's main configure script, so we don't need to list them here again
dnl (although it usually doesn't hurt).
AC_MSG_CHECKING([whether DemoProject prerequisites are satisfied])
if test "$ac_cv_header_gcrypt_h" = "yes"; then
        AC_MSG_RESULT([yes])
        rose_enable_demo_project=yes
else
        AC_MSG_RESULT([no])
        rose_enable_demo_project=
fi
AM_CONDITIONAL([ROSE_ENABLE_DEMO_PROJECT], [test "$rose_enable_demo_project" = yes])

由於專案的全部配置都封裝在“support-rose.m4”檔案中，因此重新命名、停用或刪除專案都非常簡單：只需重新命名專案目錄即可重新命名專案，透過重新命名/刪除“support-rose.m4”可以停用專案，或透過刪除專案目錄可以刪除專案。在進行任何這些更改後，應重新執行“build”和“configure”指令碼。

由於專案是 ROSE 的自包含和可選部分，因此它們不需要與 ROSE 一起分發。這使終端使用者能夠將自己的私有專案放到現有的 ROSE 原始碼樹中，而無需修改任何 ROSE 檔案，並且允許 ROSE 開發人員處理未公開分發的專案。任何不在 ROSE 的主要 Git 儲存庫中的專案目錄都不會被分發（這包括不分發 Git 子模組，儘管子模組的佔位符空目錄將被分發）。

設定 Makefile.am

[編輯 | 編輯原始碼]

每個專案至少應有一個 Makefile.am，每個 Makefile.am 由 GNU automake 和 autoconf 處理以生成 Makefile。有關這些檔案應包含的內容的詳細資訊，請參閱 automake 文件。一些重要的變數和目標是

  • include $(top_srcdir)/config/Makefile.for.ROSE.includes.and.libs: 這將引入來自更高級別 Makefiles 的定義，並且所有專案都需要它。它應該位於 Makefile.am 的頂部附近。
  • SUBDIRS: 此變數應包含所有專案子目錄的名稱，這些目錄都有 Makefiles。如果專案的唯一 Makefile 位於該專案的頂層目錄中，則可以省略它。
  • INCLUDES: 這將包含在編譯期間需要新增的標誌（類似於-I$(top_srcdir)/projects/RTC/include的標誌）。您的標誌應該放在$(ROSE_INCLUDES)之前，以確保找到正確檔案。這將引入來自 src 目錄的所有必要標頭檔案到您的專案中。
  • lib_*: 如果您要從專案中建立庫，則這些變數/目標是必需的，該庫可以稍後與其他專案或 src 目錄連結。這是處理專案的推薦方法。
  • EXTRA_DIST: 這些檔案未被列為構建最終物件所需的檔案（例如原始檔和標頭檔案），但仍必須包含在 ROSE tarball 分發版中。例如，這可能包括 README 或配置檔案。
  • check-local: 當呼叫 make check 時，此目標將從更高級別 Makefiles 中呼叫。
  • clean-local: 為您提供一個步驟來手動清理專案，例如，如果您手動建立了一些檔案（因此 Automake 不會自動清理它們）。

一個基本示例

[編輯 | 編輯原始碼]

許多專案都從翻譯器、分析器或最佳化器開始，這些翻譯器、分析器或最佳化器接受輸入程式碼並生成輸出。

將新的專案目錄新增到 ROSE 的 基本示例提交：https://github.com/rose-compiler/rose/commit/edf68927596960d96bb773efa25af5e090168f4a

請檢視差異，以便您瞭解為新專案新增和更改哪些檔案。

本質上，一個基本專案應該包含

  • 一個 README 檔案，解釋該專案的內容、演算法、設計、實現等
  • 一個翻譯器，作為專案的驅動程式
  • 根據需要新增其他原始檔和標頭檔案，以包含專案的主要內容
  • 測試輸入檔案
  • Makefile.am 用於
    • 編譯和構建翻譯器
    • 包含 make check 規則，以便您的翻譯器將被呼叫來處理您的輸入檔案並生成預期的結果

為了將您的專案連線到 ROSE 的構建系統，您還需要

  • 在 projects/Makefile.am 中為您的專案目錄新增一個子目錄條目
  • 為 每個由您的專案使用的新的 Makefile（從每個 Makefile.am 生成）在 config/support-rose.m4 中新增一行。

安裝專案目標

[編輯 | 編輯原始碼]

將專案的內容安裝到使用者指定目錄內的單獨目錄中--prefix位置。這樣做的原因是，我們不想汙染核心 ROSE 安裝空間。透過這樣做，我們可以降低 ROSE 安裝樹的複雜性和混亂程度，同時消除跨專案檔案衝突。它還使安裝樹保持模組化。

示例

[編輯 | 編輯原始碼]

此示例使用字首進行安裝。它還維護 語義版本控制。

來自 projects/RosePoly

  ## 1. Version your project properly (http://semver.org/)
  rosepoly_API_VERSION=0.1.0

  ## 2. Install to separate directory
  ##
  ##    Installation tree should resemble:
  ##
  ##    <--prefix>
  ##    |--bin      # ROSE/bin
  ##    |--include  # ROSE/include
  ##    |--lib      # ROSE/lib
  ##    |
  ##    |--<project>-<version>
  ##       |--bin      # <project>/bin
  ##       |--include  # <project>/include
  ##       |--lib      # <project>/lib
  ##
  exec_prefix=${prefix}/rosepoly-$(rosepoly_API_VERSION)

  ## Installation/include tree should resemble:
  ##   |--<project>-<version>
  ##      |--bin      # <project>/bin
  ##      |--include  # <project>/include
  ##         |--<project>
  ##      |--lib      # <project>/lib
  librosepoly_la_includedir = ${exec_prefix}/include/rosepoly

生成 Doxygen 文件

[編輯 | 編輯原始碼]

0. 安裝 Doxygen 工具

使用 MacPorts 為 Apple 的 Mac OS

  $ port install doxygen

  # set path to MacPort's bin/
  # ...

使用 LLNL 的機器之一

  $ export PATH=/nfs/apps/doxygen/latest/bin:$PATH


1. 建立 Doxygen 配置檔案

  $ doxygen -g

Configuration file `Doxyfile' created.

Now edit the configuration file and enter

  doxygen Doxyfile

to generate the documentation for your project


2. 自定義配置檔案（Doxyfile）

...

# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
# documentation are documented, even if no documentation was available.
# Private class members and static file members will be hidden unless
# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES

EXTRACT_ALL            = YES

...

# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
# and *.h) to filter out the source-files in the directories. If left
# blank the following patterns are tested:
# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh
# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py
# *.f90 *.f *.for *.vhd *.vhdl

FILE_PATTERNS          = *.cpp *.hpp

# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.
# If left blank NO is used.

RECURSIVE              = YES

...


3. 生成 Doxygen 文件

  # Invoke from your top-level directory
  $ doxygen Doxyfile


4. 檢視並驗證 HTML 文件

  $ firefox html/index.html &

5. 將目標新增到您的Makefile.am以生成文件

.PHONY: docs
docs:
    doxygen Doxyfile # TODO: should be $(DOXYGEN)
檢索自 "https://wikibook.tw/w/index.php?title=ROSE_Compiler_Framework/How_to_add_a_new_project_directory&oldid=3678474"
華夏公益教科書