Sheerpower Logo
I.4  Conditional Compilation

Conditional Compilation in SheerPower

SheerPower's conditional compilation feature uses directives like %defined, %++, %--, and %>> to let developers include or exclude parts of the code based on certain conditions. This makes it easier to adapt the software for different settings or feature sets without altering the main codebase. Developers can manage code variations efficiently, such as turning on debugging features for development while keeping the production version clean, or adjusting software capabilities for different versions. This results in software that is adaptable, efficient, and simpler to maintain.

Key Directives

  • %defined - Checks if a macro_name is defined. If defined, then %defined is said to be true.
  • %++ - Marks code that is compiled if the %defined is true.
  • %-- - Marks code that is compiled if the %defined is false.
  • %>> - Marks code that is compiled unconditionally within a %defined block.
  • %end defined - Closes the %defined block that was started with %defined.
Note: There are two addditional directives of %test and %test_ignore that are part of sheerpower's Unit Testing facility. For details see Unit Testing.

Built-in Macros

SheerPower includes built-in macros for contextual control. These macros are predefined for direct use in conditional compilation.

  1. _spversion

    The _spversion macro holds the version and build of SheerPower, formatted as V[major].[minor]. This enables version-specific coding.

  2. _user

    The _user macro contains the developer's login name, useful for user-specific script behaviors.

  3. _test

    The _test macro checks if option test on has been specified earlier in the code. If active, _test is set to 1 (true); otherwise, it defaults to 0 (false). This macro is useful for enabling or disabling test-specific code without additional flags. option test on is also set if sheerpower is envoked by sp4gl.exe /test

  4. true

    The true macro represents a boolean value of 1. It enhances code readability by explicitly indicating a true condition.

  5. false

    The false macro represents a boolean value of 0, improving clarity by making conditions for false explicit.

  6. Examples of Using Built-in Macros

    Example uses:

    %defined _spversion >= 'V011.006' %++ print "Using features available in SheerPower V011.006 or later." %-- print "Update SheerPower to use these features." %end defined %defined _user = 'admin' %++ print "Admin-specific debugging enabled." %-- print "Standard user mode. No admin-specific features enabled." %end defined

Simplest Use of %defined

The %defined directive begins a conditional block. Specify the macro_name you want to check.

macro debug_mode xxx %defined debug_mode %++ print "Debug mode is defined." %++ print "More debug mode code" %-- print "Debug mode was not defined." %>> print "This code always runs." %end defined

%defined Directive with Comparison Operators

The %defined directive in SheerPower can also utilize comparison operators to enhance conditional compilation. This allows you to compare the value of a defined macro against string constants, numeric values, or the value of another macro.

Supported Operators

  • = - Equals
  • != or <> - Not equals
  • > - Greater than
  • >= - Greater than or equal to
  • < - Less than
  • <= - Less than or equal to

Syntax

  1. To compare against a string constant: %defined macro_name [compare_oper] 'string constant'
  2. To compare against a numeric constant: %defined macro_name [compare_oper] 42
  3. To compare against the value of another macro: %defined macro_name [compare_oper] macro_arg

Components

  • macro_name - The macro whose value is to be checked.
  • compare_oper - A comparison operator.
  • 'string constant' - A string value for comparison.
  • 42 - A numeric value for comparison.
  • macro_arg - Another macro whose value is used for comparison.
Notes:
  • If the checked macro is not defined, all compares fail.
  • %defined blocks do not nest. Each %define supersedes the previous one, continuing the current block.

Examples:
macro windows_version = 10 %defined windows_version >= '11' %++ print "Windows version is 11 or higher." %-- print "Windows version is below 11." %end defined %defined windows_version >= 8 %++ print "Windows version is 8 or higher." %-- print "Windows version is below 8." %end defined macro build_type = "production" %defined build_type = "production" %++ print "This is a production build." %-- print "This is a regular build." %end defined

Compilation Logic

Within a %defined block, use %++ for code to compile if defined is true, %-- if defined is false, and %>> for unconditional code. Ensure that %end defined closes each %defined block. If any stray %++, %-- or %>> directives are found without a preceding %defined, a compile-time error will be raised.

Example Scenario

For example, in a debug configuration, certain logs or debugging lines may be included:

%defined DEBUG_MODE %++ print "Debugging information shown." %>> print "General runtime information." %-- print "No debugging information." %end defined

Using %>> for Unconditional Code

The %>> directive enables you to add code within a %defined block that always compiles, regardless of the %defined status.

Note: One of the powerful aspects of SheerPower’s conditional compilation is that any valid SheerPower statement or directive can be used within conditional compilation blocks. This includes standard statements, routine definitions, file inclusions via %include, variable assignments, and more. This feature provides a high degree of flexibility, enabling the conditional setup of entire files, modular logic, and environment-specific routines within a single block.

Benefits of Conditional Compilation

  • Tailors code for different environments, allowing debug information only in development builds.
  • Improves code maintainability by isolating environment-specific code.
  1. Debugging and Logging
    Enable detailed logging and debugging statements only in development builds. This keeps production builds cleaner and faster, with only essential information output.
  2. Platform-Specific Code
    Conditionally compile code to adjust for differences across platforms (e.g., Windows vs. Linux). This simplifies maintaining a single codebase while allowing platform- specific adjustments.
  3. Feature Toggles
    Enable or disable certain features based on build requirements, such as premium features for paying customers. This approach allows for easy differentiation between feature- limited and full versions of the application.
  4. Optimized Code for Performance
    Include performance-enhancing code only in builds intended for high-performance environments. This way, non-critical builds stay lightweight, while critical builds gain from optimizations.
  5. Development Stage Customization
    Tailor code for different development stages, like Alpha, Beta, or Production, by including stage-specific messages or experimental features. This approach helps communicate the application’s state and includes or excludes features based on maturity.

For more information on defining macros, see the Macros and Blueprints tutorial.

Hide Description

    

        


      

      
Enter or modify the code below, and then click on RUN

     

    		

  

  
  

    
    

    
  
  

  
  

  
 

  



    

    Looking for the full power of Sheerpower? 
    

    Check out the 
   
   Sheerpower website.
   
   Free to download.  Free to use.
  

  		
  
  

  


 

Wide screen