Obfuscate
                                =========

         Quick and dirty POC to obfuscate an S*BASIC source file


What Obfuscate does
===================

This program suite strips away as much useful information from a target
program as possible to produce a fully working program, but one that
conceals how it works or what it originally looked like.

After processing, a few corrections may have to be made by hand to restore
full functionality, but such corrections should normally be few and minor.

This program suit is merely a proof of concept. It is not intended to be a
pretty, or robust, or fully fledged tool. Much more obfuscation can be
done, eg by compressing or muddying structures and the like.


Compatibility and Limitations
=============================

This program is probably not error free! Check the Troubleshooting guide at
the end of this document if you get stuck!

The programs in their source form only run under SMSQ/E's SBASIC; the
compiled versions should run under Qdos + TK2 + Knoware's most recent Q2S
compatibility toolkit.

All SuperBASIC dialects can be processed. However, Obfuscater relies on the
tokenised form of the source code, and there are some older _sav file
formats it cant cope with. Just re-save such target programs with a newer
version of QSAVE.

Note: A second pass (Pass2_obj) has been added as a separate program. It
      is called automatically on completion of pass1 (Obfuscate_obj). Its
      output goes to ram1_final_bas.

      Unfortunately this arrangement means that the Home Thing is now
      required. Or simply modify the programs yourself to do without!


To Use:
=======

1. Load the target S*BASIC program, ie a program you wish to obfuscate, into
   the interpreter.

2. QSAVE it

   Note: All toolkit commands used in the target program must be present
   in the system!

3. EXecute Obfuscate_obj and enter the name of the QSAVEd target
   file and press ENTER (or just press ENTER on its own to quit).

   Note: If you want to LRUN Obfuscate_bas in the main SBASIC interpreter
   you must first LRESPR the PEEKSTR_bin toolkit. Under SMSQ/E you can
   simply EXecute Obfuscate_bas directly.

4. If all went well, the resulting file should end up as ram1_test_bas
   and ram1_final_bas. final_bas is the most processed file.

5. LOAD ram1_final_bas to see whether there are any MISTakes (There
   shouldn't be). If there are, try the same with ram1_test_bas and fix
   any fixable lines. Then EXecute Pass2_obj again.

6. SAVE the final file in the location it is intended to be run from.
   This should now be a functional copy of the original target program.

7. LRUN (or EXecute, depending on how you crafted your program) the newly
   the final_bas file from its proper location. It should now work exactly
   like the original.

8. Most errors, if any, can be corrected by comparing the original target
   file with the processed file.


End notes
=========

If you feel there are systemic errors, let me know!

Please feel free to develop this program or write your own! Better still,
Dont obfuscate your source code, so others can fix any problems they find -
and learn from your failures as well as your triumphs!


Troubleshooting
===============

Q: When LOADing the processed program I get the error message: unknown
   procedure or similar, without a line number.
A: Probably the line length in the target program exceeds the limit set.
   Increase the $$buff and WIDTH settings and recompile both Obfuscate and
   Pass2

Q: I get a "not found" error on a line like OPEN#3; V33, or FTEST(V56)
A: Unquoted file and device names in target program will not work!
   Compare the lines in the target program with the processed program and
   change a line such as OPEN#3; V33 to OPEN#3; 'ser1', and FTEST(V56) to
   FTEST("win1_myprog_bas")

Q: I get errors like At line 149:1 error in expression on a line like
   IF V106%("Menus") <> V137%: V446 'This program NEEDS QMenu to run'
A: V106% probably refers to a m/c toolkit that was not present at the time
   the target file was QSAVEd.
   All external toolkits that the program uses must be present in the
   system (or SBASIC daughter interpreter) when the program is QSAVEd

Q: I get errors like At line 149:1 error in expression on a line like
   IF TSTTHG%("Menus") <> V137%: V446 'This program NEEDS QMenu to run'
A: Similar to the question above, but this time the toolkit was present
   during QSAVEing, but is no longer present in the system.
   All external toolkits that the program used when the program was QSAVEd
   must be present in the system (or SBASIC daughter interpreter) when the
   program is RUN.

Note: Compiler directives, such as REMark $$buff= or REMark %%filename
   etc are removed during processing. If needed add them back manually.


Program status
==============

V0.01, pjw, 2025 Feb 19, based on program LISTer V0.03
V0.02, pjw, 2025 Feb 20, Some small changes; added Pass2, updated manual


               Conditions of use and DISCLAIMER as per Knoware.no

Generated by QuickHTM, 2025 Feb 20