Compile Setting

This setting lets you describe in the Chutzpah.json file how to execute a command which can compile your source files to .js files. You tell Chutzpah what to execute and some information about what your executable does (like where to find the generated .js files). Then after running the executable Chutzpah can associate each source file with each output file to still give the nice behavior of mapping tests back to their original files.

You should ideally configure this compile setting to use the same mechanism you have for compiling the code in your project. This will give you a nice performance gain when running Chutzpah since it will re-use the .js files you have already built. This becomes really powerful when you are taking advantage of IDE integration features that TypeScript and CoffeeScript plugins have that provide a compile on save experience. If configured correctly Chutzpah will be able to use the the output of that feature and never need to actually invoke the compile step. This results in a very fast test running experience.

Field Default Description
Extensions [] The extensions of the files which are getting compiled (e.g. .ts).
ExtensionsWithNoOutput [] The extensions of files which take part in compile but have no build output. This is used for cases like TypeScript declaration files which share a .ts extension. They have .d.ts extension and are part of compilation but have no output. You must tell Chutzpah about these if you want the SkipIfUnchanged setting to work. Otherwise Chutzpah will think these are missing output.
SourceDirectory Chutzpah.json directory The root directory where all the sources the command compiles are below. This lets Chutzpah know where in the out dir it should find each reference file
OutDirectory Chutzpah.json directory The directory where the compiled files are output to
WorkingDirectory Chutzpah.json directory This is the working directory of the process which executes the command.
Executable null The path to an executable which Chutzpah executes to perform the batch compilation. Chutzpah will try to resolve the path relative to the settings directory. But if can’t find the file there you must give it a full path.
Arguments null The arguments to pass to the command
Timeout 30000 (5 minutes) How long to wait for compile to finish in milliseconds?
SkipIfUnchanged true Skips the execution if all files Chutzpah knows about are older than all of the output files. This is defaulted to true but if you hit issues since it is possible Chutzpah might not know about all the files your compilation is using then you can turn this off. Ideally you should tell Chutzpah about these files using the references and tests settings since this setting helps Chutzpah not need to even invoke the executable if it figures out it’s not needed.
Mode Executable Determines how this compile setting is used. By default it is in Executable mode where it will require you provide an executable which Chutzpah will run if it sees it finds missing .js for input file. If you set this to External then Chutzpah will ignore the Executable, Arguments settings and assume you have some external process which is compiling. In this case Chutzpah will use the SourceDirectory and OutDirectory options to try to find your .js files for the input files. If it can't find them it will trace an error but still attempt to proceed.


For the Executable, Arguments and OutDirectory fields Chutzpah lets you put in variables which get expanded at execution time. These can be system environment variables like %comspec% as well as the set of Chutzpah provided variables below:

Variable Description
%chutzpahsettingsdir% The directory the chutzpah.json is in
%clrdir% The directory to the folder where the CLR is. This folder contains programs like msbuild.exe
%msbuildexe% The path to msbuild.exe
%powershellexe% That path to powershell.exe
%cmdexe% An alias for %comspec% which is the path to cmd.exe.

Integration with compilation tooling

Many users of TypeScript and CoffeeScript use IDE tooling which will already provide compilation of those files to JavaScript. In that case you should Compile Mode setting to External. This tells Chutzpah to assume that some external force is doing the compilation and that Chutzpah can just count on the JavaScript file to exist where you said they would be.

Examples

As part of this release I have included several examples which show different combinations of these settings. Below I will highlight three examples. One runs your compilation code using a .bat file, one uses a .ps1 file and the last runs an MSBuild project file. For each of these samples I will cover some interesting parts but for a complete picture please browse the full code of the samples.

All of the samples below assume you have tsc.exe in your system path.

Using a .bat file

This sample demonstrates compiling TypeScript files in place using a .bat filed called compile.bat.

chutzpah.json
{
 "Compile": {
   "Extensions": [".ts"],
   "ExtensionsWithNoOutput": [".d.ts"],
   "Executable": "compile.bat"
  },
 "References": [
   {"Include": "*/src/*.ts", "Exclude": "*/src/*.d.ts" }
 ],
 "Tests": [
   { "Include": "*/test/*.ts", "Exclude": "*/test/*.d.ts" }
 ]
}


compile.bat

@echo off
tsc src/code.ts test/test.ts --sourcemap 


A couple interesting things about this example:
  1. It doesn’t set the outdirectory since the compile.bat command is compiling them in place.
  2. It gives a relative path for compile.bat since it is in the same directory as the chutzpah.json file
  3. It provides .d.ts as the ExtensionsWithNoOutput since although .d.ts are part of the compilation process they produce no output. This helps Chutzpah be smart about when it needs to run the compile executable.


Using a .ps1 file

This sample demonstrates compiling TypeScript files to a out directory using a PowerShell file.

chutzpah.json
{
 "Compile": {
   "Extensions": [".ts"],
   "ExtensionsWithNoOutput": [".d.ts"],
   "OutDirectory": "out",
   "Executable": "%powershellexe%",
   "Arguments": "-NoProfile %chutzpahsettingsdir%\\compile.ps1"
  },
 "References": [
   {"Include": "*/src/*.ts", "Exclude": "*/src/*.d.ts" }
 ],
 "Tests": [
   { "Include": "*/test/*.ts", "Exclude": "*/test/*.d.ts" }
 ]
}

compile.ps1
tsc src/code.ts test/test.ts --sourcemap --declaration --outDir out

A couple interesting things about this example:
  1. It sets the outdirectory in the chutzpah.json to match the outDir setting in the call to tsc.exe in compile.ps1. This tells Chutzpah where to find the .js files.
  2. It uses the %powershellexe% variable that Chutzpah provides to get the full path to powershell.exe in the executable field.
  3. It uses the %chutzpahsettingsdir% variable in the arguments field to build the full path to the compile.ps1.


Using an MSBuild project file

This sample demonstrates compiling TypeScript files to an out directory by executing a target in an MSBuild project file.

chutzpah.json
{
 "Compile": {
   "Extensions": [".ts"],
   "ExtensionsWithNoOutput": [".d.ts"],
   "Executable": "%msbuildexe%",
   "Arguments": "/t:CompileTS ",
   "OutDirectory": "out"
  },
 "References": [
   {"Include": "*/src/*.ts", "Exclude": "*/src/*.d.ts" }
 ],
 "Tests": [
   { "Include": "*/test/*.ts", "Exclude": "*/test/*.d.ts" }
 ]
}

compile.proj
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
 
 <PropertyGroup>
   <TscExe>tsc</TscExe>
 </PropertyGroup>
 
 <Target Name="CompileTS">
   <Exec Command="$(TscExe) src/code.ts test/test.ts --declaration --sourcemap --outdir out" />
 </Target>
  
 
</Project>


A couple interesting things about this example:
  1. The %msbuildexe% variable that Chutzpah provides is used in the executable field to get the full path to msbuild.exe.
  2. The arguments field calls the compile.proj using a specific target (CompileTS). You may notice this command doesn’t mention the project file compile.proj. In this sample it is assuming that is the only project file. If you wanted to be explicit you could change the arguments to: compile.proj /t:CompileTS

Last edited May 7 at 2:34 PM by mmanela, version 6