brands · South Africa
CODESYS Library Structure: Versions, Namespaces and Reuse
Build a clear CODESYS library: source and compiled formats, namespaces, placeholders, effective versions, dependency checks and practical release testing.
A useful CODESYS library packages a clear interface, documented behaviour and identifiable dependencies so another project can use it deliberately. The work is more than moving a copied function block into a separate file. Consumers need to know what the library expects, which version is resolved, what state it owns and how a proposed update has been checked.
This guide covers library structure, source and compiled formats, namespaces, placeholders, installation and version review. A fictional dependency exercise shows why an unchanged top-level library name can still lead to changed behaviour. It is intended for South African PLC learners, training centres and teams developing reusable educational or engineering code.
This workflow concerns the CODESYS 3 development environment. The vendor development-system overview places library reuse within that environment; check the tooling supplied for your course before following a different product generation's workflow.
Decide what belongs in the library
Start with one coherent responsibility. A unit conversion, a small data-validation function or a reusable study counter can have a clear contract. Code tightly coupled to one machine's addresses, credentials or process assumptions may need an application-specific adapter before it can be shared sensibly.
The fact that code has been copied twice is a reason to review reuse, not an automatic instruction to publish it as a general library. Compare the two uses. If they differ in reset behaviour, units or ownership, forcing them into one interface without explaining the differences can create a confusing collection of switches.
Write down the intended consumers and supported use cases. State the inputs, outputs, valid ranges, initial state and failure behaviour. If a caller must invoke a function block in a particular way, document that expectation. A consumer should not need to inspect every private implementation detail to use the public interface correctly.
The function block versus function guide helps distinguish reusable calculation from reusable state. That distinction matters before packaging: a function block instance may retain state between calls, while a stateless transformation has a different testing and ownership model.
Keep the application boundary visible
Separate the reusable calculation from the point where application data enters it. A library that accepts a documented value and returns a documented result can be easier to test than one that silently reads a project-specific global variable. The application can remain responsible for obtaining and validating the source data.
This is a design choice to evaluate, not a claim that every library must be completely independent of a device. Device-dependent libraries exist and have legitimate purposes. Identify the dependency explicitly so consumers know which runtime, device description or supporting package is part of the environment.
Understand the library formats
CODESYS documents source libraries as .library and protected libraries as .compiled-library or .compiled-library-v3. A .library file should not be described simply as a compiled binary. The same documentation distinguishes interface and container libraries, which serve different packaging purposes.
Choose the format from the distribution requirement and supported environment. A classroom may need source visibility so learners can inspect implementation details. A supplier may distribute a protected implementation with a documented interface. In either case, consumers still need meaningful usage instructions and evidence about supported behaviour.
Source protection is not proof that code is correct. Source availability is not proof that someone has reviewed it. Keep questions about visibility, origin, licensing, compatibility and testing separate. A file extension answers only part of the packaging question.
When preparing an exercise, tell learners whether they are expected to inspect source, read interface documentation or treat the library as a component with a published contract. Assessment should match the access they actually have.
Give the library a stable identity
The CODESYS library properties reference places metadata in Project Information and describes fields including Company, Title, Version, DefaultNamespace, Description and Placeholder. Use the applicable documentation for the installed release when setting those properties.
A useful description states the library's responsibility and important boundaries. “Utility functions” is less informative than “Educational integer range checks with explicit invalid-input results.” Names should help a consumer decide whether the library belongs in the project before opening individual objects.
Record a release identity that can be distinguished from development work. Keep the source and the distributed package associated with that identity. If two files claim the same released version but contain different behaviour, the version label has stopped providing reliable traceability.
For a training library, include a short release note explaining the exercise specification, known limitations and test evidence. Do not label it production-ready merely because a small consumer programme builds successfully. Its intended scope should travel with the package.
Namespace and library title serve different purposes
A namespace qualifies access to symbols. It can make the origin of a function or function block visible in a consumer's source. A title identifies the library in its management context. Similar spelling does not make the concepts interchangeable.
The Library Manager documentation describes namespace-qualified access and an effective version after placeholder resolution. Use those fields when recording what a consumer actually references. A namespace by itself does not identify the resolved package version.
For a fictional library called StudyMath, a qualified symbol such as StudyMath.ClampValue makes the intended symbol origin easier to recognise. It does not say which release implements ClampValue. Keep the dependency record alongside the code review.
Install the package, then reference it deliberately
CODESYS documents Save Project and Install in the Library Repository in the File menu. It saves the library into the local system repository so it can be inserted into a project. Installation and adding a reference to a consumer are separate steps.
Avoid teaching a fixed repository filesystem path as though it applies to every installation. Use the installed environment's repository management and document the arrangement supplied for the class or team. The consumer should be able to locate the intended package without relying on an undocumented folder copied from another workstation.
After adding a reference, inspect its identity, namespace and resolution. Build a minimal consumer that calls one documented operation with a known valid input and checks the result. This confirms more than seeing the package name in a repository list, while still remaining only a limited integration check.
For team distribution, retain the approved package, documentation and required dependencies through the organisation's chosen controlled process. State who maintains it and how consumers learn about updates. Sharing a file without ownership or release notes leaves the next project to reconstruct the assumptions.
Understand placeholders and the effective version
A placeholder is a reference that resolves to a specific library version; it is not a promise that dependencies are irrelevant. CODESYS documents placeholder resolution through application and environment context, including device descriptions and library support packages. The guidance notes that library profiles are no longer supported from SP17 onward.
For a project review, record both the reference and the effective version used in the application. If an application overrides a resolution, make that choice visible. A consumer needs to know the result of resolution rather than merely the symbolic name written in a library hierarchy.
An unresolved placeholder is missing information to investigate. Do not automatically choose the newest available package solely to remove an error indicator. Find the required environment and compatibility information, then test the proposed resolution against the application's needs.
Likewise, a fixed version is useful for reproducibility but does not prove that the version is appropriate. It can preserve a known baseline, including known limitations. Updates should be deliberate changes with a reason and evidence, rather than either automatic upgrades or permanent avoidance of all new releases.
Worked exercise: the same top-level name, different dependency
The fictional training application RangeStudy uses a library called StudyReport, version 1.0.0.0. StudyReport depends on a placeholder named StudyRange. The exercise supplies two classroom environments: Bench A resolves StudyRange to 1.0.0.0, while Bench B resolves it to 1.1.0.0.
The top-level StudyReport identity is unchanged. The resolved dependency differs. This is a paper model of dependency recording, not an example of a real CODESYS package or an assertion that all placeholders follow these invented version choices.
| Environment | Direct library | Placeholder | Effective dependency |
|---|---|---|---|
| Bench A | StudyReport 1.0.0.0 | StudyRange | StudyRange 1.0.0.0 |
| Bench B | StudyReport 1.0.0.0 | StudyRange | StudyRange 1.1.0.0 |
The exercise specification requires a valid input when an integer is between 0 and 100 inclusive. Version 1.0.0.0 implements that rule. The candidate 1.1.0.0 mistakenly excludes 100 while keeping the same input and output types. The version number is an invented label; it is not evidence that the change is compatible.
A test using input 50 passes on both benches. A reviewer who checks only that case might conclude that the environments are equivalent. Add the upper boundary 100 and the behaviour differs: Bench A accepts it, while Bench B rejects it.
Build a boundary-focused comparison
Use the inputs -1, 0, 50, 99, 100 and 101. Under the required inclusive range, the expected results are false, true, true, true, true and false. Under the altered rule they are false, true, true, true, false and false.
| Input | Required inclusive range | Altered candidate | Match? |
|---|---|---|---|
| -1 | False | False | Yes |
| 0 | True | True | Yes |
| 50 | True | True | Yes |
| 99 | True | True | Yes |
| 100 | True | False | No |
| 101 | False | False | Yes |
One failing case is enough to reject the claim that the candidate satisfies this stated range requirement. Five matching cases do not cancel that contradiction. The useful result is the identified boundary defect and its dependency context, not a percentage presented as a general quality score.
Now remove the effective-version record from Bench B. The observations still reveal a mismatch with the requirement, but attribution to a particular library release is unresolved. Restore the dependency evidence before reporting which package caused the difference. A plausible guess is not a traceable diagnosis.
Separate interface compatibility from behaviour compatibility
In the fictional example, the operation still accepts an integer and returns a Boolean. A consumer can retain the same call shape while the result at 100 changes. Interface compatibility therefore does not establish behaviour compatibility for the application's requirement.
A release review should identify changes to names, types, units, valid ranges, initial conditions, error handling and state transitions. Some changes are obvious at the call site; others only appear in selected tests. Describe which dimension changed rather than treating “compatible” as an unexplained single label.
Choose a versioning convention and document it for consumers. CODESYS metadata and a team's release convention are not the same thing. A version number can communicate intent, but it cannot independently verify that the author followed the convention or that the consumer's use case remains valid.
For the study defect, a corrected candidate should accept 100 and reproduce the expected results for all six chosen inputs. Retain the failing trace with the correction so the regression case remains understandable. Do not delete the boundary test once the immediate issue is fixed.
Add a consumer-level check
The range function may be correct while the application uses it incorrectly. Suppose the consumer converts input 100 to 101 before calling the function. Both library versions then reject the supplied value, but that does not prove the original input is outside the required range.
Record the value at the library boundary and the value at the application's input boundary. This distinguishes a library behaviour issue from an adapter or conversion issue. The data conversion guide provides further practice in making those transformations explicit.
A useful test plan therefore includes the library contract and at least one representative consumer path. The two checks answer different questions. Passing the isolated function cases does not automatically validate the caller's units, conversions or interpretation of the result.
Document stateful components with equal care
A stateful library component needs more than an input-output table for isolated values. Describe initial state, update order, call expectations and reset behaviour. Two independent consumers should not accidentally share one instance's memory unless that sharing is an intentional part of the design.
For example, two virtual counters may each need their own previous-sample state. A package containing a correct counting algorithm can still be used incorrectly if the consumer calls one instance for both signals. The defect belongs in the interaction between the interface and the caller, so documentation should make ownership obvious.
The CODESYS language-choice guide includes a sampled rising-edge example. Use a sequence of observations to check stateful behaviour and label the observation model. A single snapshot cannot establish that a component handles repeated true inputs or reset transitions correctly.
If a library operation depends on a periodic call, state that requirement and check it in the actual target environment. Do not infer timing guarantees from a package name or a successful isolated call. Keep paper-model results separate from measured runtime behaviour.
A practical release review for a small teaching library
Begin by checking that the public documentation and implementation describe the same contract. Read the valid ranges and error behaviour, then select cases that could contradict them. Include the boundary cases that were difficult during development, not only examples that demonstrate the intended happy path.
Next, create a clean consumer project using the documented package and dependency arrangement. Confirm that another learner can reproduce the setup without access to an unexplained development folder. Record missing packages or assumptions as documentation defects to fix before distributing the lesson.
Then compare the candidate release with the previous exercise baseline. Explain what changed and which consumer tests were repeated because of that change. A new description may require a documentation review; a changed range rule requires behaviour checks. Scale the evidence to the actual change.
Finally, retain the package identity, source reference where available, environment description, test results and release note together. The goal is a reviewable teaching artefact, not a large folder whose contents cannot be connected. A future instructor should be able to identify exactly what the class used.
This process does not certify a library for industrial deployment. It develops the habits needed to make reuse understandable and reproducible. Production use requires the relevant engineering review and target-specific evidence beyond the educational examples here.
Common library problems and useful first questions
If a package is missing, first check the required identity and repository arrangement. Installing an unrelated package with a similar name may replace one clear error with a more confusing behaviour difference. Obtain the expected dependency information before changing the environment.
If the placeholder is unresolved, inspect the intended resolution context and required target or supporting package. If the effective version differs between workstations, compare those environments explicitly. A direct library name that matches on both machines does not prove the dependency hierarchy matches.
If a symbol is ambiguous, inspect its namespace and qualification. Avoid changing several unrelated references at once. A small qualified consumer call can help establish which symbol is intended, after which the application can be reviewed systematically.
If a build succeeds but an exercise fails, return to the requirement and capture the inputs at the component boundary. The PLC troubleshooting guide supports this evidence-first approach. Compilation, dependency resolution and functional correctness are related checks, but they answer different questions.
What South African training buyers should request
Ask whether the course teaches consuming libraries, developing them or both. A lesson that adds an existing package is useful, but it is not the same as designing an interface, documenting a release and testing an update. Request a practical example that matches your objective.
For a college or private training centre, ask how learner environments are reproduced across workstations. Confirm the required packages, access rights and retained exercise materials. A dependency exercise is especially useful when it deliberately includes a missing or changed resolution and asks learners to explain it.
For an engineering team, choose a small approved component for the learning brief and use sanitised data. The goal might be to document one interface and reproduce a consumer test on a second workstation. This produces a concrete outcome without exposing confidential application code.
Our guide for PLC training centres can help define the evaluation criteria for supporting educational software. Compare the full access and teaching arrangement using the South African PLC course cost guide, including software and follow-up practice where needed.
Use simulation for the right part of the lesson
This site is commercially connected to PLC Simulation Software. Its Structured Text practice resources can support logic preparation within the current educational feature set. Check the documented scope before expecting a specific vendor library operation.
The product's PLC programme testing resources can help learners practise requirements and boundary cases. This guide does not claim that the product installs CODESYS libraries, resolves native placeholders or imports compiled vendor packages.
Complete the packaging lesson in the actual CODESYS environment supplied for the course. Label which evidence comes from a paper exercise, educational simulation or native development-system work. That distinction makes a learner's portfolio easier to assess and prevents an introductory exercise from being mistaken for full platform experience.
Questions about CODESYS library structure
Is a .library file the same as a compiled library?
No. CODESYS distinguishes source libraries from protected compiled formats. Choose the format from the distribution and compatibility requirements, and provide useful interface documentation regardless of source visibility.
Does installing a library add it to every project?
No. Installation makes the package available in the repository. A consumer still needs the intended reference and dependency resolution. Confirm the effective version and test a documented call in the consumer environment.
Does a placeholder always mean the newest version?
No. A placeholder resolves in an application and environment context to a specific version. Inspect the effective result and document overrides. Choosing the newest package without a compatibility review is not a substitute for understanding the required dependency.
Can an update break behaviour without changing the interface?
Yes. The fictional range example keeps the same input and output types but changes the result at 100. Boundary tests expose that difference. Version labels and successful compilation do not replace checks against the consumer's requirement.
What makes a useful library portfolio exercise?
Provide a small documented interface, identifiable package and dependency versions, a reproducible consumer, selected tests and a release note. Include one corrected defect with its evidence. A reviewer should be able to understand the scope and reproduce the result.