Confused about Project->Source Files vs Component->API files

Tip / Sign in to post questions, reply, level up, and achieve exciting badges. Know more

cross mob
JoBr_1593366
Level 5
Level 5
100 sign-ins 50 questions asked 100 replies posted

I have a library project from Cypress that contains code in the "Header Files" and "Source Files" section of the Source tab, as well as in the "API" section of the Components tab. 

I don't really understand the difference between them.  I know the API code is templates, and they get converted into Generated_Source files inside the Application that uses the component, with the templates filled-in.

It also seems like I need to modify the "Source Files" to do what I want.

The "Source Files" and "API" files are largely identical, though, and I don't understand why the same code exists in both places.

I watched the tutorials on building your own components and it kind of explained this but I still don't get it.

"The library code is for the entire project, not associated with any component.  The Components tab is for the components contained in this library."  So I get that a library can contain multiple components, and the API gets converted into Generated_Source for a particular instance of a component, but I don't understand how all of that interacts with the code in the Source tab that isn't associated with any particular component.

0 Likes
1 Solution

JoBr,

You are correct.  Cypress'  CyComponentLibrary.cyprj  has ONLY API code and no library shared code in "Source Files".  (I suppose that's why it's call Component Library).  However, they could have had files in "Source Files" if they felt it desirable to have shareable code amongst the components.

I take it from your previous post that the "secret" project 'works'-ish.  Kinda ... sorta.  But you want to 'fix' or 'improve' the code.  You can move the files in the "Source Files" folder to the component(s) if you want.  You can also componentize the API calls with `$INSTANCE_NAME` and soft-code the parameters if you'd like.

What I don't get is  why 'they' created a library with hardcoded component(s) and component parameters.   They could have just easily gave you TopDesign schematic pages that you could copy into your TopDesign.

Len
"Engineering is an Art. The Art of Compromise."

View solution in original post

5 Replies
Len_CONSULTRON
Level 9
Level 9
Beta tester 500 solutions authored 1000 replies posted

JoBr,

I don't know if this will answer your question but here goes ...

The "Header Files" and "Source Files" section of the Source tab are files that you have full control.

The "Generated_Source" files are automatically generated by the "Application" Build phase.  Although you could modify these files in the sections listed in the files, it is generally not highly recommended.   This is because modifying outside of allowed sections would be overwritten in the next "Application" Build phase.

The Components tab should be only used for advanced users.   It is intended for new component creation and/or copied component modifications.  I don't recommend using the contents of this tab unless you've done your homework.

Correction 5.20.22021:

The "API" files in the component tab are intended for generating the .c and .h files for the component found in the "Generated_Source" folder.  They have special formatting which includes `$INSTANCE_NAME` that gets replaced at the time of Application Build phase with the instance name of the component from the TopDesign.   Modify any of these files at your peril.   Again.  It is for advanced users that need to do their homework before trying to alter any of them.

Len
"Engineering is an Art. The Art of Compromise."

Well I definitely have to modify files in both locations, which is why I'm trying to understand how they work.  🙂

When you place a component in a schematic, the ones under API get converted into the Generated_Source, but it's not clear to me what happens with the files under "Source Files" inside a library project.

0 Likes

JoBr,

I'm assuming since you are seeing an "API" folder in the "Components" tab you have imported a component into your project.   Normally the "API" folder doesn't show up in this tab unless you specifically import the component.

As I indicated in my earlier corrected post that `$INSTANCE_NAME` is one of the templated variables that get substituted with the instance name you gave the component in TopDesign.  There are other template substitutions.

You stated:

The "Source Files" and "API" files are largely identical, though, and I don't understand why the same code exists in both places.

This statement shouldn't be true.  The "API" folder is used to create files in the "Generated_Source" directory of the project in the "Sources" tab.

You stated:

... it's not clear to me what happens with the files under "Source Files" inside a library project.

A library project can be used to create a library of components AND/OR a library of common code.

You seem to have a handle on the component side of the library (These elements are located in the "Components" tab.)

If you add files in the "Header Files" or "Source Files" in the "Source" tab, it can create code that can be shared across projects.  Note:  The templating feature of the components may not work on the code found in the "Source" tab.  (Never tried it.)  This is probably because there is no instancing therefore no instancing name.

An example of using a library for common code is creating a special text manipulation function.  Let's call it ReverseChars().   You would define the function's .c file and prototype the function in a .h file.   It can now be used across project if the library is referenced in the Build.

Here's an interest feature to consider.   If you create a library to share with others and include the source and header files, the library code gets recompiled each time the user's project gets built.

If you do not want to share the library source files but want to share the library this can be done.  This could be useful to keep your function implementations proprietary.  Useful if you want to sell the library.   Seggar does this for many of their implementations such as emFile and emWin libraries.  However, they can sell you a license for the source code.

If you want to keep your source code a secret you need to do the following:

  • Provide the header files (so that the user's build can succeed without error).
  • Build your library under all the configurations and CPUs you plan to support.  This generates the .o files to be used in the link phase of the user's project.  The configurations to consider are: "Debug" and "Release".  The CPUs are the CPUs used by the PSoCs you plan to allow to use your code.  This includes the ARM CM0, CM0+, CM3, CM4, CM7 and the 8051 (for the PSoC3).   This can be set in the "Build Settings ..." for the library. (See pic below.)
    Len_CONSULTRON_0-1621512551498.png

     

  • Once all the configurations are compiled (without error), you can archive the library.
  • Last step.  Remove the .c files from the library that reference your functions.  (Keep the .h files.)

Does this answer your questions?

Len
"Engineering is an Art. The Art of Compromise."

I looked through CyComponentLibrary.cyprj and there is no Source Files code at all, just API code, and it's all templatized with `$INSTANCE_NAME`.

The project I'm working on has some in the Source Files folder and some in the API folder, and some in both.  Almost none of it is templatized for INSTANCE_NAME, so it doesn't work if you change the name of the component from default (but you normally wouldn't).

It was originally a "secret" project, but then they stopped supporting it and just gave us the source, which is why it has the duplicated code, I guess.  The versions in the Source Files folder have all the templated Symbol Parameters hardcoded.

If I disable Code dependency for that library, it stops working because some functionality only exists in the Source Files section.  So I think I need to disable that, then move any files from the Source Files section into the API section until it works again, consolidating any changes to the files that are in both, and delete all the ones in the Source Files section so it behaves more like a standard component, with all the code in the API section.

0 Likes

JoBr,

You are correct.  Cypress'  CyComponentLibrary.cyprj  has ONLY API code and no library shared code in "Source Files".  (I suppose that's why it's call Component Library).  However, they could have had files in "Source Files" if they felt it desirable to have shareable code amongst the components.

I take it from your previous post that the "secret" project 'works'-ish.  Kinda ... sorta.  But you want to 'fix' or 'improve' the code.  You can move the files in the "Source Files" folder to the component(s) if you want.  You can also componentize the API calls with `$INSTANCE_NAME` and soft-code the parameters if you'd like.

What I don't get is  why 'they' created a library with hardcoded component(s) and component parameters.   They could have just easily gave you TopDesign schematic pages that you could copy into your TopDesign.

Len
"Engineering is an Art. The Art of Compromise."