====== 44 Packed Project Libraries ======

===== General Notes =====

  * Packed Project Libraries (PPLs) only contain compiled code (no BD)
  * when you create a debug build for a PPL, you can view the block diagram of each VI.
  * 1 PPL = 1 lvlib
  * only public VIs can be seen
  * PPLs expose your API (they are not part of the exe)
  * cannot create documentation for PPLs by programmatically parsing (must be generated before build from source and copied into the calling project to be included there)
  * If a VI calls a PPL compiled for one target, and you open the VI on another target that has a different operating system, the PPL fails to load.
  * build exe will be smaller, because compiled PPLs are saved separately
  * PPLs show version number in explorer (not working for RT Target?)
  * PPLs store dependencies relative to each other
  * best practice: store all PPLs in one flat hierarchy
  * you can use Diagram Disable Structures to see if you are inside a PPL and use different paths etc
  * PPLs are self-contained: All dependencies (eg from vi.lib) will be stored in the PPL as well
      * can lead to multiple copies of the same VI in RAM (FGVs won't work, for example)

---- 

===== Notes for building PPLs =====

  * preparation:
     * wrap in lvlib, if not already done
     * for each lvlib use one repository and one lvproj
     * examine dependencies, start bottom-up: libraries, classes, framework, modules
  * build options:
    * check: always exclude dependent packed libraries
    * uncheck: connector pane setting callers adapt at run time
  * Conditional Disable Structures may be used to build two PPLs with two lvprojs on base of the same VIs
  * must be built for each target, can be tricky: dependencies also include PPL e.g. ''B-PPL'' needs ''A-PPL''
    * save A-PPL build for windows in PPL-folder
    * open project for building B-PPL for windows
    * B-lvlib-VIs are linked to A-PPL in PPL-folder
    * build B-PPL for windows
    * swtich A-PPL build for windows against A-PPL build for RT Phar Labs in PPL-folder
    * open project for building B-PPL for RT Phar Labs
    * build B-PPL for RT Phar Labs


<WRAP center round tip 100%>
**Don't build PPLs which depend on PPLs inside <vi.lib>**. The PPL will contain a broken link to <vi.lib> which prevents the PPL from loading. We're still trying to figure out what is going on here. We already have a minimal example for further investigation.

{{ :kb:labview:pplandvilib.zip |}}

  - build both PPLs to repo\builds
  - copy dependency.lvlibp to vi.lib\PPLandViLib
  - open Top.lvproj which depends on vi.lib\PPLandViLib\dependency.lvlibp 
  - build top.lvlibp, so top is now linked to dependency in vi.lib
  - open a blank project and drag in top.lvlibp from repo\builds 
  - it won’t open, because it cannot find dependency.lvlibp, which hasn’t moved since building top.lvlibp.

{{:kb:labview:pasted:20230628-121017.png}}

</WRAP>

==== Notes for introducing PPLs ====

  * if needed, move code which should be replaced into lvlib
  * replace lvlib with PPL
  * **don't forget to move remove old code from lvlib, if you have added it for this process**

---- 

===== Dynamic VI calls =====

Normally you would call VIs from ''vi.lib'' statically, so that they will be pulled into the PPL. In certain scenarios it might be useful (?) to call a VI outside of the PPL, which needs to happen dynamically. **This works with LV native datatypes on the connector pattern only**, e.g. if you hand over a class between the PPL and the other VI it won't work out of the box. The class being pulled into the PPL will get namespaced resulting in a new class name which is not compatible with the class outside the PPL. See [[https://forums.ni.com/t5/LabVIEW/dynamic-call-VI-outside-a-PPL-with-a-class-and-in-another/m-p/4313457|this thread]]. 

This might be the cause for this error when using Call By Reference:

    Error 1031 occurred at Open VI Reference in PPL.lvlibp:Call By Reference.vi
    Possible reason(s):
    LabVIEW:  VI Reference type does not match VI connector pane.

#todo: solve with inheritance


---- 

===== Notes for using DQMH =====

  * since DQMH as a dependency would be pulled into each DQMH-Module-PPL, it may be usefull to create a DQMH-PPL
    * move the three DQMH classes from ''vi.lib\Delacor\Delacor QMH\Libraries'' into a lvlib
    * create PPL
    * move the three classes out of the lvlib
  * in a DQMH Modul Project:
    * move the three DQMH classes from ''vi.lib\Delacor\Delacor QMH\Libraries'' into a lvlib
    * replace lvlib with the created DQMH-PPL
    * move the three classes out of the lvlib
    * now your DQMH module depends on the DQMH-PPL
    * if you create new requests (use scripting tools) they will use the original DQMH and not the DQMH-PPL
    * you need to replace the dependency again
    * these steps should be automated during building ?

==== to be clarified ====

  * public DQMH Poly Message VI, but implementations are private, I needed to change them to public
  * hse-application paths not working out of the box
    * GetVersion should not throw an error (not related to PPL)
  * HSE-Framework has a dependency to project.lvlib
  * cannot build hse-libraries separatly (circle-dependency: hse-config <-> hse-application)

---- 

===== HSE PPL flavour =====

The evolution of PPL usage at HSE. Each evolution needs to include the steps from 
previous evolutions.

==== Building PPLs ==== 

example: hse-licence-library
  * set build destination for PPL to ''<reporoot>\PPL''
  * rat-buildr builds one specific PPL
  * rat-packagr creates .zip and rat-deployr copies it to release folder on NAS
  * those two steps might be triggered multiple times to generate the PPL for different LV versions, bitnesses, OS

==== Using PPLs ==== 

example: hse-licence-editor
  * the used PPLs are stored as .zip files at ''<reporoot>\PPL''
  * for developing the PPLs must be unpacked, but are added to .gitignore
    * lvproj. contains a virtual folder ''PPL'' which contains the used ''.lvlibp''
    * source code which is using PPLs always refers to those PPLs inside the project repo
  * for building with rat, the zips need to be extracted, before the project is being opened
    * add ''<reporoot>\Source\unzip PPLs.vi''
    * set ''XXX_INIT_CUSTOM_VI: "/unzip PPLs.vi"'' in rat.yml
    * save unzipped PPLs from init stage for other stages (see [[code:commercial:rat:install:configuration-gitlab#dependencies|gitlab dependencies]])

    artifacts:
        paths:
        - PPL/*.lvlibp

==== Using PPLs & release via VIP ==== 

//not implemented, yet//

challenges:
  * the installed VIs should contain the version -> source distribution should be build
  * multiple PPLs as zip files need to be included into one VIP, after installation only the correct one will be present at ''<vi.lib>''. 
  * VIs should be able to link to dependency PPL statically
Problems
  * when building the source distribution, no .lvlibp file can be present, because of files output hierarchy
  * when building the VIP the projects VIs will be broken, because .lvlibp is missing and VIPBuilder will abort
ideas:
  * call the dependency PPLs dynamically
  * exclude ppl from source dist and use a post-built-custom-vi to copy content from <root>\PPL to <buildSpecDest>\PPL


==== Building PPLs & release via VIP ==== 

challenge: While creating the PPL the dependent PPLs need to be present. While building the VIP, only the zip files needs to be present - but also the zip files just created in this pipeline. //example: hse-licence-manager//

  * create additional ''<name>-vip.lvproj'' file with a source distribution build specification
    * create additional wrapper VIs at ''Source\VIP'' which dynamically call the installed PPL, if needed
    * add ''<reporoot>\PPL'' as autopopulating folder (to allow zip files, which are created later)
    * add ''<reporoot>\Source\unzip PPLs.vi''
    * in src_dist buildspec include PPL folder and needed sources; built into ''<reporoot>\builds\src_dist''
    * when building the source distribution, make sure, that no .lvlibp file is present at ''<reporoot>\PPL''
  * configure .vipb file
    * use ''<reporoot>\builds\src_dist'' as Source Directory
    * create PPL destination e.g. ''<vi.lib>Hampel Software Engineering\HSE Licence Manager\PPL'' and use this for the PPL folder
    * deploy ''unzip PPLs.vi'' to the correct level in the hierarchy e.g. ''\PPL'' or ''\Source''
    * add ''Post-Install Custom Action.vi'' which calls the installed ''unzip PPLs.vi''
    * add ''Post-Uninstall Custom Action.vi'' which deletes the installed folder (because unpacked .lvlibp won't get deleted automatically)
  * have one or multiple pipelines which build, package and deploy the PPL as zip to the NAS
    * add ''PPL_BLDR_CLEARBUILDDEST: "FALSE"'' in rat.yml to allow building into ''<reporoot>\PPL'' and having dependency PPL there at the same time 
  * after the build PPL stages, have a stage to build the VIP
  * to copy the needed zip files back into ''<reporoot>\PPL'' add ''VIP_INIT_COLLECTDESTINATION: "../PPL"'' in rat.yml

---- 

===== interesting links =====

  * [[https://forums.ni.com/t5/Community-Documents/Resolution-of-Pseudopaths-in-LabVIEW-Per-Target-Invocation-of/ta-p/4087124|Resolution of Pseudopaths in LabVIEW (Per-Target Invocation of Packed Project Libraries)]] (NI Forums)
  * [[https://labviewwiki.org/wiki/NIWeek_2019/Code_Trafficking:_Smuggling_Your_Best_Software|Code Trafficking: Smuggling Your Best Software]] @ 27:00 (NIWeek 2019, LabVIEWWiki)
  * [[https://forums.ni.com/t5/Actor-Framework-Discussions/AF-PPL-on-linux-RT/td-p/4101233| AF PPL on linux RT]] (Actor Framework, NI Forums)
  * [[https://zone.ni.com/reference/en-XX/help/371361R-01/lvhowto/caveats_recommend_packed/|Caveats and Recommendations for Packed Project Libraries]] (NI Online Help)
  * [[https://forums.ni.com/t5/LabVIEW-Idea-Exchange/Manual-specification-of-dependency-locations-without-including/idi-p/4198824|Manual specification of dependency locations without including dependencies in build spec]] (LabVIEW Idea Exchange)
  * [[https://forums.ni.com/t5/LabVIEW-Idea-Exchange/Make-LVLIBs-work-hassle-free-in-executables/idi-p/2269278|Polymorph]] (Idea Exchange)
  * [[https://forums.ni.com/t5/DQMH-Consortium-Toolkits/Best-practice-when-using-an-DQMH-API-in-PPL-Plugins/td-p/3904419?profile.language=en|Best practice when using an DQMH API in PPL Plugins]] (NI Forums)
  * [[https://forums.ni.com/t5/DQMH-Consortium-Toolkits/my-DQMH-PPL-and-VILIB-PPL-best-practices/td-p/4155993|(my) DQMH PPL and VILIB PPL best practices]] (NI Forums)
  * [[https://forums.ni.com/t5/DQMH-Consortium-Toolkits/Bigger-DQMH-Project-Number-of-Modules-and-VI-s/m-p/4201700/highlight/true#M1913|Re: (Bigger) DQMH Project, Number of Modules and VI's]] (NI Forums)
  * [[https://labviewwiki.org/wiki/NIWeek_2019/Effectively_Using_Packed_Project_Libraries|NIWeek 2019/Effectively Using Packed Project Libraries]]
  * [[https://forums.ni.com/t5/Community-Documents/Debugging-Symptoms-Build-Namespacing-Missing-VIs-in-Compiled/ta-p/4112286|Debugging Symptoms - Build Namespacing - Missing VIs in Compiled Executable or PPL Code Appears to not Run]]
  * [[https://forums.ni.com/t5/Community-Documents/Debugging-Symptoms-Packed-Project-Library-PPL-Dependencies/ta-p/4107786|Debugging Symptoms - Packed Project Library PPL Dependencies - Searching for Dependencies Dialog When Running Executable]]