Deprecated: Insert/Clean and Its Cache

Contents

Deprecated workflow. Use Bind for new projects. insert/clean and their -cache option remain available for existing projects and cases not supported by Bind. This status does not remove the commands or announce a removal date. It does not apply to Go/compiler build caches.

1. Existing projects

trice insert writes numeric IDs into calls before compilation and updates TIL/LI. trice clean removes those IDs or restores zero placeholders after compilation. If the project stores inserted sources, Clean is optional. For a new project use Bind; for a supported migration follow Insert to Bind.

Keep the accumulated TIL and local LI. Rebuild firmware after ID changes. This chapter also retains historical implementation explanations; for current assignment, range and ordering rules use IDs and dictionaries.

2. Importing existing IDs with add

Both trice add and trice insert can collect existing numeric IDs into TIL/LI. Add guarantees unchanged source files. It is not a required preparation step for Insert.

Behavior add insert
Collect existing IDs into TIL/LI ✅ Yes. ✅ Yes.
Call without an ID Leaves it alone. Assigns an ID.
ID already maps to a different message Reports the conflict; leaves the source unchanged. Assigns another eligible ID and changes the source.
Write source files Never. When needed. 
trice(iD(123), "Existing");
trice("New");

With a conflict-free ID 123, Add collects the first mapping; Insert also gives the second call an ID. Add is useful for importing already instrumented library sources or recovering mappings still present in a firmware’s source snapshot. It cannot recover deleted messages or the historical mapping of ID-free Bind sources. Preserve TIL/LI rather than relying on reconstruction.

Add is a specialist helper, not itself declared deprecated by the status of the Insert/Clean workflow. It creates no Bind sidecars. See the implementation and source-preservation test.

The trice insert and trice clean commands are parsing and modifying the source code files. Even this is a reasonable fast procedure, this could get time consuming on large projects, especially when using these commands as permanent pre-compile and post-compile steps. It is assumed, that usually between 2 compile steps not all project files are changed. The project files majority will stay unchanged despite the ID insertion and removal. This repeated parsing and modifying of unchanged source code is avoidable with the Trice cache technique. Also it could get annoying to recompile files all the time only because they got Trice IDs removed and inserted. With the Trice cache we get also a solution not to re-compile un-edited files as well.

3. Trice Cache Idea

Lets talk about just one source file $HOME/my/src/foo.c and imagine we process many in one shot.

4. Trice Cache Logic

When id.TriceCacheEnabled is true (applied -cache CLI switch) and the folder ~/.trice/cache exists, we have

5. Trice Cache Remarks

Should the .trice/cache be better located inside the project folder? What, if the user has several projects and several users on the same machine working on projects together? What about libraries containing trice code?

6. Trice Cache Tests

Nr Action cCache iCache ID state Edited state Test function
0,1 0:clean 0:inval 0:inval 0:cleaned X:any Test_0_1_0000X_clean_on_invalid_cCache_invalid_iCache_cleaned_file
2,3 0:clean 0:inval 0:inval 1:inserted X:any Test_2_3_00011_clean_on_inalid_cCache_invalid_iCache_inserted_edited_file
4,5 0:clean 0:inval 1:valid 0:cleaned X:any Test_4_5_0010X_clean_on_invalid_cCache_valid_iCache_cleaned_file
6 0:clean 0:inval 1:valid 1:inserted 0:not Test_6_00110_clean_on_invalid_cCache_valid_iCache_inserted_not_edited_file
7 0:clean 0:inval 1:valid 1:inserted 1:yes Test_7_00111_clean_on_invalid_cCache_valid_iCache_inserted_edited_file
8 0:clean 1:valid 0:inval 0:cleaned 0:not Test_8_01000_clean_on_valid_cCache_invalid_iCache_cleaned_not_edited_file
9 0:clean 1:valid 0:inval 0:cleaned 1:yes Test_9_01001_clean_on_valid_cCache_invalid_iCache_cleaned_edited_file
10 0:clean 1:valid 0:inval 1:inserted 0:not Test_10_01011_clean_on_valid_cCache_invalid_iCache_inserted_not_edited_file
11 0:clean 1:valid 0:inval 1:inserted 1:yes Test_11_01011_clean_on_valid_cCache_invalid_iCache_inserted_edited_file
12 0:clean 1:valid 1:valid 0:cleaned 0:not Test_12_01100_clean_on_valid_iCache_valid_cCache_clean_file_not_edited
13 0:clean 1:valid 1:valid 0:cleaned 1:yes Test_13_01101_clean_on_valid_iCache_valid_cCache_clean_file_edited
14 0:clean 1:valid 1:valid 1:inserted 0:not Test_14_01110_clean_on_valid_iCache_valid_cCache_inserted_file_not_edited
15 0:clean 1:valid 1:valid 1:inserted 1:yes Test_15_01111_clean_on_valid_iCache_valid_cCache_inserted_file_edited
16,17 1:insert 0:inval 0:inval 0:cleaned X:any Test_16_17_1000X_insert_on_invalid_cCache_invalid_iCache_cleaned_file
18,19 1:insert 0:inval 0:inval 1:inserted X:any Test_18_19_1001X_insert_on_invalid_cCache_invalid_iCache_inserted_edited_file
20,21 1:insert 0:inval 1:valid 0:cleaned X:any Test_20_21_1010X_insert_on_invalid_cCache_valid_iCache_cleaned_file
22 1:insert 0:inval 1:valid 1:inserted 0:not Test_22_10100_insert_on_invalid_cCache_valid_iCache_inserted_not_edited_file
23 1:insert 0:inval 1:valid 1:inserted 1:yes Test_23_10101_insert_on_invalid_cCache_valid_iCache_inserted_edited_file
24 1:insert 1:valid 0:inval 0:cleaned 0:not Test_24_11000_insert_on_valid_cCache_invalid_iCache_cleaned_not_edited_file
25 1:insert 1:valid 0:inval 0:cleaned 1:yes Test_25_11001_insert_on_valid_cCache_invalid_iCache_cleaned_edited_file
26,27 1:insert 1:valid 0:inval 1:inserted X:any Test_26_27_1010X_insert_on_invalid_cCache_valid_iCache_cleaned_file
28 1:insert 1:valid 1:valid 0:cleaned 0:not Test_28_11100_insert_on_valid_cCache_valid_iCache_cleaned_not_edited_file
29 1:insert 1:valid 1:valid 0:cleaned 1:yes Test_29_11100_insert_on_valid_cCache_valid_iCache_cleaned_edited_file
30 1:insert 1:valid 1:valid 1:inserted 0:not Test_30_11110_insert_on_valid_cCache_valid_iCache_inserted_not_edited_file
31 1:insert 1:valid 1:valid 1:inserted 1:yes Test_31_11111_insert_on_valid_cCache_valid_iCache_inserted_edited_file

7. Possible Trice Cache Editor-Issues And How To Get Around

8. Activating the Trice Cache

mkdir -p ~/.trice/cache

9. Source editing and editor support

10. Avoiding False-Positive Editor Warnings

When the user writes

trice("msg: Hello! 👋🙂\n");

after trice insert this gets

trice(iD(123), "msg: Hello! 👋🙂\n");

and the compiler builds and then with trice clean, this gets again

trice("msg: Hello! 👋🙂\n");

Sophisticated editors may detect the missing ID and warn by underlining the trice command:

x

To avoid this you can add the following line to your project specific triceConfig.h file:

#define TRICE_CLEAN 1

The Trice tool, will change the value to 0 and change it back to 1, when performing the ID insertion and cleaning, when this line occurs inside the triceConfig.h file. This way these false-positive editor warnings are avoidable:

x x

It is recommended to use the Trice cache in conjunction with this to avoid a permanent re-translation of files including Trice code.

TRICE_CLEAN==1 changes all Trice macros into empty ones. It is used only to silence sophisticated editors. In the cleaned state, when the IDs are removed from the files, the editor could underline the Trice macros indicating a false positive.

Do not use TRICE_CLEAN for disabling Trice macros. The triceConfig.h line #define TRICE_CLEAN 0 changes to 1 with every trice clean and to 0 with every trice insert. This line is optional and must not be in a different file. If you want to disable Trice macros use TRICE_OFF.

11. Legacy parser examples

12. Trice in source code comments

13. Trice parser exclusion markers

Use TRICE_INSERT_OFF and TRICE_INSERT_ON markers to exclude a source section from trice insert, trice clean, trice add and ID refresh parsing.

// TRICE_INSERT_OFF
TRice("This text is ignored by the trice tool.");
// TRICE_INSERT_ON

The markers are case-sensitive, must be written as comments, and affect only the Trice tool parser. TRICE_INSERT_OFF without a following TRICE_INSERT_ON disables Trice parsing until the end of the file. The marker state is local to the scanned file and does not affect source files including that file. This is useful for Trice target sources or other source sections containing Trice-like comments or helper macros that should not create or change IDs.

13.1. Avoid it

13.1.1. Parser Limitation

Because the implemented source code parser for trice insert and trice clean is only a simple one, there is one important limitation:

trice( "hi 0" );
// An "allowed" example comment.
trice( "hi 1");
// An \" allowed example comment.
trice( "hi 2");
// A " NOT allowed example comment. This disrupts the parsing.
trice( "hi 3");
// A " NOT allowed example comment. This enables the parsing after a disruption.
trice( "hi 4");

13.1.2. Trice macros in header files

13.1.3. Trice macros inside other macros

There is nothing wrong, when putting Trice macros into other macros. But: When running the self made macro, the location information of the inner trice macro will point to the self made macro definition and not to its execution location.

Example: When Functions fnA and fnB are executed, the MY_MESSAGE location information points to file.h and not into the appropriate lines inside file.c.

file.h:

#define MY_MESSAGE trice("msg:Hi\n"); // self made macro

file.c:

void fnA( void ){
  ...
  MY_MESSAGE
  ...
}

void fnB( void ){
  ...
  MY_MESSAGE
  ...
}

13.1.4. Upper case only TRICE macros should be written with id(0), Id(0) or ID(0)

The stamp size 0, 16 or 32 is usually controlled by writing trice, Trice or TRICE or for upper case only Trice macros by using id(0), Id(0) or ID(0). When writing TRICE("hi"); for example, the Trice CLI switch -defaultStampSize controls the ID insertion, but this is then equal for all new TRICE messages.

14. Limited Trice Parser Capabilities

The Trice tool internal parser has only limited capabilities. In works well in most cases, but could lead to problems in some cases. The compiler run will for sure end up with some error messages in the following examples, so the developer can fix the code.

An example, provided by @KammutierSpule, is this:

void trice0_test() {
    Trice0( "OK");
    Trice( InvalidUse );
    Trice( "%u", Variable );
}

void trice0_test() {
    Trice0( iD(2740), "OK"); // ok, iD is added
    Trice( InvalidUse ); // no warning or error
    Trice( "%u", Variable ); // id is not added / inserted
}

As said, the compiler will complain about that in any case.

15. Insert implementation and workflow details

15.1. Starting Conditions

@@ To understand this chapter you should look into the Trice tool source code. @@

15.2. Aims

15.3. Method

15.3.1. Trice Insert Initialization

// insertIDsData holds the insert run specific data.
type insertIDsData struct {
    idToFmt    TriceIDLookUp     // idToFmt is a trice ID lookup map and is generated from existing til.json file at the begin of SubCmdIdInsert. This map is only extended during SubCmdIdInsert and goes back into til.json afterwards.
    fmtToId    triceFmtLookUp    // fmtToId is a trice fmt lookup map (reversed idToFmt for faster operation) and kept in sync with idToFmt. Each fmt can have several trice IDs (slice).
    idToLocRef TriceIDLookUpLI   // idToLocInf is the trice ID location information as reference generated from li.json (if exists) at the begin of SubCmdIdInsert and is not modified at all. At the end of SubCmdIdInsert a new li.json is generated from itemToId.
    itemToId   TriceItemLookUpID // itemToId is a trice item lookup ID map, extended from source tree during SubCmdIdInsert after each found and maybe modified trice item.
    idToItem   TriceIDLookupItem // idToItem is a trice ID lookup item map (reversed itemToId for faster operation) and kept in sync with itemToId.
}

Until here the algorithm seem to be ok.

15.4. User Code Patching (trice insert)

15.5. User Code Patching Examples

15.6. Exclude folders & files from being parsed (pull request 529)

The pull request #529 introduces key enhancement:

    -exclude Flag
    Introduces a command-line flag -exclude that allows users to specify one or more source addresses to be omitted from scanning or processing. This improves flexibility in environments with known noisy or irrelevant sources.

-exclude Flag Example

The -exclude flag can be used multiple times to omit specific files or directories from scanning. Wildcards are not supported.

trice insert -v -src ./_test/ -exclude _test/src/trice.h -exclude _test/generated/

15.7. ID Usage Options

15.8. General ID Management Information

15.8.1. Option Cleaning in a Post-build process

15.8.2. Option Let the inserted Trice ID be a Part of the User Code

15.8.3. Option Cleaning on Repository Check-In

16. TRICE_CLEAN

TRICE_CLEAN is an optional editor aid for the legacy Insert/Clean workflow. Normally leave it undefined; the library defaults to 0. Bind sidecars let editors resolve ID-free calls without this setting.

If your editor reports false macro-argument warnings after trice clean, you can explicitly define TRICE_CLEAN in your project’s triceConfig.h only. Use 0 for inserted sources or 1 for already cleaned sources. trice clean changes the existing definition to 1; trice insert and trice bind reset it to 0. The tool never adds this definition automatically.

The compiler sees this value too: TRICE_CLEAN=1 suppresses ordinary logging code. Run Insert or Bind before building firmware that must log. For deliberately disabling logging, use TRICE_OFF instead. trice bind does not introduce a new global TRICE_MODE.

With -v, Bind prints a note when it finds a TRICE_CLEAN definition in a scanned triceConfig.h. The note explains that Bind normally does not need this optional Insert/Clean editor aid. If Bind plans to reset 1 to 0, it reports that change explicitly. This is informational and does not fail the command. With -dry-run, the planned reset is reported but not written; without -v, these notes are omitted.

If TRICE_CLEAN exists in triceConfig.h:

16.1. trice clean After trice bind

Bind-owned Trice calls already contain no IDs greater than zero. Therefore, trice clean does not remove IDs from them and deletes neither sidecar includes nor sidecars.

With an existing definition:

#define TRICE_CLEAN 0

trice clean changes it as before to:

#define TRICE_CLEAN 1

The library then uses the clean/off path. Existing sidecars remain as artifacts but do not produce normal logging code.

Without TRICE_CLEAN, running trice clean after a bind run has practically no effect:

Running trice bind again resets an existing definition to 0 and updates the sidecars.

TRICE_CLEAN=1 disables logging; it does not make an included header optional. If an owner sidecar or rebase helper is physically missing, the compiler may still report a missing include even in a disabled build. Regenerate the files with trice bind before compiling; do not delete isolated include lines to silence the error.

17. Re-Migration to trice insert

A public re-migration subcommand is still not part of the normal user workflow. However, the repository helper script for returning to the clean state uses the same validated bind re-migration as the tests. It removes complete rebase include pairs, their helper headers, sidecar includes, and owner sidecars together, and corrects the affected lines in li.json.

Anyone performing the return manually must remove all related artifacts and must not leave behind an individual begin or end include line. The previous workflow then follows:

trice insert
Build

18. Appendix: TRICE_CLEAN States at a Glance

State TRICE_CLEAN Own sidecar active Effect
Inserted undefined or 0 ❌ No Explicit TIDs from the source
Bound undefined or 0 ✅ Yes TIDs from the sidecar
Clean/Off 1 — Existing clean/off path

Tool effect when the definition exists:

Tool Effect on TRICE_CLEAN
trice insert sets it to 0
trice clean sets it to 1
trice bind sets it to 0

If the definition is absent, trice bind does not add it.

19. Automated pre-build insert command example

trice i -v -i ../../../til.json -src ../src -src ../lib/src -src ./

This is a typical line you can add to your project as an automatic pre-compile step.