使用 Phantom 來自動建置 .NET 專案

先前嘗試用 IronRuby + Rake,好不容易把必要工具都裝好了,也學了點 Ruby 語法,卻發現它無法正確處理中文字元,於是改用原先 survey 的選項之一:Phantom

這篇筆記會說明 Phantom 的安裝步驟,並展示一個實際專案的建置腳本。

安裝 Phantom

Phantom 沒有安裝程式,只要到官網下載最新版本的壓縮檔,解開到本機的某個資料夾就行了,例如:C:\Tools\Phantom。

檔案下載的對話窗有提供 source code 和 package 的下載連結,參考下圖。


要注意的是,Package 的壓縮檔只包含可執行檔。如果你是下載 0.2 版的 package(Phantom-0.2.zip),它在執行 MSBuild.exe 時,預設是去執行 .NET Framework 3.5 版的 MSBuild.exe。也就是說,它可以建置 Visual Studio 2008 的專案,但如果碰到 Visual Studio 2010 的專案,就會建置失敗。此時,你必須在建置腳本中透過 msbuild 物件的 toolPath 屬性來指定 .NET Framework 4 的 MSBuild.exe 的完整路徑,參考這篇說明文件:MSBuild Integration

如果你下載的是包含完整 source code 的版本,此版本(v0.3)就是使用 Visual Studio 2010 來編譯,且預設使用 .NET Framework 4 的 MSBuild.exe,不過,你必須自行建置整個 Phantom 專案。由於 Phantom 本身就是用 Phantom 建置腳本 build 出來的,所以建置的過程非常簡單,只要執行原始碼套件中的 build.bat 就行了。

如果你希望在任何地方都能執行 Phantom.exe,可以將它的所在路徑加入環境變數 PATH。

安裝完成之後,我用一個簡單的建置腳本來確認它能夠正確處理中文字元,接著便開始為我目前的 .NET 專案動手編寫 Phantom 建置腳本。

編寫 Phantom 建置腳本

Phantom 建置腳本的檔案名稱是 build.boo,這個檔案必須使用 UTF-8 編碼,否則建置腳本中的中文字會變成亂碼。副檔名 .boo 已經告訴你,檔案內容是以 Boo 程式語言來撰寫。這部份的語法並不難,只要參考一下現有的建置腳本範例(例如 Phantom 專案本身的建置腳本),依樣畫葫蘆,動作快的人應該花個半小時就可以為自己的 .NET 專案寫好建置腳本。我算是動作慢的吧!(沒辦法,還得一邊寫筆記、抓圖、以及一堆有的沒的微調....)

我直接拿一個自己的類別庫專案來試,以下就是最後完成的建置腳本:

solution_file = "src/HuanlinLib.sln"
assembly_info_file = "src/AssemblyInfo_Global.cs"
configuration = "Release"

desc "預設的 target"
target default, (init, build, deploy, package):
  pass

desc "建置前的初始化動作"
target init:
  rmdir("build")

desc "清除編譯過程產生的檔案(讓原始碼保持乾淨)"  
target clean:
  rmdir("build")
  rmdir("src/Huanlin/bin")
  rmdir("src/Huanlin/obj")   
  rmdir("src/Huanlin.Braille/bin")
  rmdir("src/Huanlin.Braille/obj")   
  rmdir("src/Huanlin.TextServices/bin")
  rmdir("src/Huanlin.TextServices/obj") 
  // ....其餘省略

desc "建置專案"
target build:
  print "產生新的組件版本編號..."
  exec("UpdateVersion.exe", "-b Increment -r Automatic -i ${assembly_info_file} -o ${assembly_info_file}")
  
  print "建置專案..."
  msbuild(file: solution_file, configuration: configuration)

desc "將建置輸出結果複製到 'build' 資料夾"
target deploy:
  print "複製檔案到 build 資料夾..."
    
  with FileList(): 
    .Include("readme.txt")
    .ForEach def(file):
      file.CopyToDirectory("build/${configuration}")

  with FileList("src/Huanlin/bin/${configuration}"):
    .Include("*.{dll,exe}")
    .ForEach def(file):
      file.CopyToDirectory("build/${configuration}/HuanlinLib")

  with FileList("src/Huanlin.Braille/bin/${configuration}"):
    .Include("*.{dll,exe}")
    .Include("Braille.ini")
    .ForEach def(file):
      file.CopyToDirectory("build/${configuration}/HuanlinLib")

  // ....其餘省略

desc "建立 zip 壓縮檔"
target package:
  zip("build/${configuration}", 'build/HuanlinLib.zip')
(是不是比 XML 格式的建置腳本清爽、好讀多了呢?)

重點說明:
  • Line 2:定義一個變數:assembly_info_file,此變數稍後會用到。由於我的類別庫專案包含多個子專案,而且我想要讓每個子專案所 build 出來的組件都有相同的版本編號,因此我讓各專案共用一個 AssemblyInfo 檔案。在建置專案之前,只要先修改這個共用檔案裡面的版本編號即可。修改版本編號的動作也是自動的,稍後就會看到。
  • Line 6:定義預設的建置目標(target),名稱是 default。此 target 相依於另外四個 targets,依序是:init、build、deploy、package。也就是說,當我們用 Phantom 來執行建置腳本時,在執行 default target 之前,會先依序執行前述四個相依的 targets。
  • Line 7:只有一行 'pass',表示這裡沒有其他動作需要執行。
  • Line 10~11:建置前的初始化作業,這裡只有一個動作:刪除建置輸出的資料夾。
  • Line 25~30:build target,此區段包含建置專案的指令,主要有兩個動作:
    (1) 產生組件版本編號;
    (2) 執行 MSBuild.exe 來建置 solution 或 project。

    產生組件版本編號的工作,我是用 UpdateVersion 這個免費工具來幫我自動遞增版本編號。其實 Phantom 也有提供產生 AssemblyInfo 檔案的功能,需要的話可以參考這篇討論串:Assembly versioning

執行建置腳本

執行建置腳本的命令很簡單,只要執行 Phantom.exe,它就會在現行目錄下尋找建置腳本 build.boo,有找到的話就會自動執行預設的 target。你也可以加上命令列參數,明確指定要執行哪個 target,例如:

D:\Tools\Phantom\Phantom.exe  clean

官網的文件有完整的參數說明。

我是仿照 Phantom 專案的作法,在建置腳本 build.boo 的所在目錄下建立一個批次檔,檔名是 build.bat,內容如下:

@echo off
"..\..\3rd Party Tools\Phantom\v0.3\Phantom.exe" %*

因此,每次要建置專案時,我只要執行 build.bat 就行了。其中的參數 "%*" 代表 build.bat 命令後面帶的所有參數(如果有的話)。

小結

可能因為 Phantom 是用 C# 和  Boo 撰寫,加上我之前有用 IronRuby + Rake 寫過建置腳本的緣故,我覺得 Phantom 還蠻容易上手的,未來也有打算再為其他 .NET 專案編寫 Phantom 的建置腳本,並加上單元測試的 target。

在編寫建置腳本的過程中,我也重新檢視並調整了專案的目錄結構,讓整個目錄結構變得更乾淨、更清楚。比如說,增加一個 build 目錄,專用來存放自動建置的輸出檔案。此外,版本控制的設定也稍有變動,例如對整個專案原始碼的資料夾指定 svn:ignore 屬性,把 bin 和 obj 資料夾都加入忽略清單。

Copyright © 2012. Huan-Lin 學習筆記 - All Rights Reserved
Powered by Blogger
Template Design by Cool Blogger Tutorials
Published by Templates Doctor