Skip to content

CLI User Guide

Jump to bottom
oleg-shilo edited this page Jul 11, 2017 · 32 revisions

Deployment

As many other tools CS-Script provides an intensive command line interface that can be used from shell/terminal (e.g. Bash, PowerShell, command-prompt). This interface is particularly useful fo environments like Linux, where working from terminal is a predominate development approach.

CS-Script deployment model exist in two distinctive distribution forms:

  • Simple
    Applicable for Windows, Linux, Mac. Basically it is an XCopy approach when yuo can bring on the target system CS-Script binaries that you need. Typically it is the script engine executable (cscs.exe). While you may also want to bring CSSRoslynProvider.dll along but strictly speaking cscs.exe is all you need ro run C# scripts.

  • Complete
    Applicable for Windows only. This model involves much dipper integration with the host OS. It involves bringing the software package (7z archive) from GitHub Releases folder unpacking it and launching the config console (css_config.exe), which performs all necessary configuration steps. Alternatively you can perform a single step deployment via the Chocolatey CS-Script package. The Complete deployment/distro contains much more than CS-Script binaries (Simple distro). It also includes extra utilities and binaries targeting various rintimes and the documentation.

    Full distro content (click to expand)   - Integration with OS: system path, envars, shell-extensions, default editor association
      - GUI configuration console
      - NuGet and Wsdl third-party tools
      - Collection of utility scripts
      - Binaries targeting legacy runtimes (e.g. .NET 3.5)
      - Complete set of Roslyn binaries
      - Intensive _Samples_ library
      - Documentation

While Complete distro contains many useful resources the Simple one is what you would need in 90% of the cases. The script engine CLI is designed in such a way that it (single executable) can produce the minimal set of CS-Script documentation, samples and required configuration. The Simple distro is applicable for all OSs and as such it is perfect as a basic environment for a crash-course in CS-Script.

Quick Start

Note, if you are running CS-Script on Mono you will always need to supply the mono token for all commands: mono cscs.exe -ver instead of cscs -ver. However this document contains all samples written in the short form for the sake of simplicity.

Creating and executing sample script

  • cscs -s - prints sample script. For C# 7 sample use -s:7 switch.
  • cscs -s > sample.cs - redirects sample script content into sample.cs file.
  • cscs sample.cs - execute sample.cs file

Produced sample.cs file

using System;
using System.Windows.Forms;

class Script
{
    static void Main(string[] args)
    {
        for (int i = 0; i < args.Length; i++)
            Console.WriteLine(args[i]);

        MessageBox.Show("Just a test!");
    }
}

Hints and tips

  • You can print the list of all supported commands with cscs -cmd

  • You can access help for a specific command by typing ? after the command name (e.g. cscs -syntax -?)

  • You can print the whole overview of CS-Script specific C# directives with cscs -syntax

  • The most common/useful CS-Script directives that you can specify directly in the script are:

  • With the -pc switch you can define a precompiler script that allows pre-processing the primary script content prior its execution. Precompilation allows achieving pretty advanced functionality usually available in some advanced AOP framework. For example code decoration, macros unfolding etc.

  • Instead of passing arguments from the command line you specify them directly in the script code with //css_args directive.

  • The most frequently used command line arguments can be specified in the global configuration so they will be automatically added during an the execution for all scripts (e.g. suppressing warnings).

  • On Windows/.NET you can pass //x as the very last argument of the script and this will trigger a Debug.Assert on entering the script code. This way you can attach system wide debugger and debug the script:

    cscs print.cs "Hello World!" //x

C# 7 Support

CS-Script uses at runtime C# compiling infrastructure available with .NET/Mono. The highest supported C# syntax version available out of box is C# 5 on .NET and C# 6 on Mono. The support for C# 7 on both platforms is available via a separate compiling infrastructure - Roslyn. Read more...

CS-Script integrates with Roslyn via special CS-Script code provider assembly CSSRoslynProvider.dll

This is how you can enable CS-Script C# 7 support (Roslyn integration):

  • On Mono:
    Since Roslyn is a part of Mono you only need to place CSSRoslynProvider.dll in the same location where your cscs.exe is.
    Alternatively specify the location of the provider dll in the global configuration as the UseAlternativeCompiler config value.

  • On .NET:
    Roslyn is not a part of .NET binaries and it needs to be installed separately. CS-Script Complete Distro includes Rolsyn and it is enabled by default on all fresh installations. If you need to enable Roslyn manually read about the procedure in this dedicated guide

Command Line Interface

Note, this section does not cover the whole CLI but only highlights its most important elements. The whole CLI documentation can be generated with cscs -? command. You can also access its latest copy here.

Command: version

Syntax: cscs -ver (or just cscs)

Description: Prints full information about the current CS-Script environment.

Command: commands

Syntax: cscs -cmd

Description: Prints list of supported commands (arguments).

Syntax: cscs -cmd ?

Description: Prints description of an individual command.

Syntax: cscs -e <script_file>

Description: Compiles script into an application executable.

Syntax: cscs -co:<options>

Description: Passes user specified options into C# compiler.

The sample below demonstrates how to compile unsafe code. Any unsafe code requires passing /unsafe parameter to the C# compiler:

using System;
using static dbg;

unsafe void main()
{
    int i = 25;
    SquarePtrParam(&i);
    print(i);
}

unsafe void SquarePtrParam(int* p)
{
    *p *= *p;
}

Syntax: cscs -ac

Syntax: cscs -pc

Syntax: cscs -pvdr

Still Under Development

Pages

Clone this wiki locally